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Chapter 1. Print this topic 


You can view or download the PDF version of these topics: 


* |Cryptographic hardware] (about 756 KB or 292 pages) contains all of the 


information regarding IBM® cryptographic hardware supported for the iSeries’ 
server at V5R2. 


* [4758 Cryptographic Coprocessor| (about 753 KB or 296 pages) contains 


information regarding the 4758 Cryptographic Coprocessor hardware supported 
for the iSeries server at V5R2. 


Saving PDF files 


To save a PDF on your workstation for viewing or printing: 
Right-click the PDF in your browser. 

Click Save Target As. 

Navigate to the directory in which you would like to save the PDF. 
Click Save. 


Pon > 


Downloading Adobe Acrobat Reader 


If you need Adobe Acrobat Reader to view or print these PDFs, you can download 
a copy from the|Adobe Web site 


(www.adobe.com/ products /acrobat/readstep.html 


>. 
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Chapter 2. What’s new for V5R2 


If you are looking for the latest information regarding new cryptographic 
hardware, and added features to existing cryptographic hardware options for 
iSeries servers, you have come to the right place. 


a 
New cryptographic hardware: IBM 2058 e-Business Cryptographic Accelerator 


The IBM 2058 e-Business Cryptographic Accelerator (Hardware Feature code 4805, 
and hereafter referred to as the 2058 Cryptographic Accelerator) is available, in 
addition to the 4758 Cryptographic Coprocessor. Designed to improve iSeries 
performance by rerouting the processing of private keys away from the system 
processors, this hardware option is an excellent choice for iSeries implementations 
that handle high volumes of SSL (Secure Sockets Layer) transactions. While the 
2058 Cryptographic Accelerator is an excellent choice for enhancing the SSL 
performance of iSeries servers, and is easy to install and intialize, it does not offer 
the wide range of configuration options that the 4758 Coprocessor offers. 


Additional function: 4758 Cryptographic Coprocessor 

The 4758 Cryptographic Coprocessor offers customers the following new 
capabilities: 

* Financial pin processing: Unique key per transaction (UKPT) 

* Common Cryptographic Architecture (CCA) 2.4 


New cryptographic hardware scenarios 


To give you some ideas on how you can use cryptographic hardware with your 
iSeries server, we have added the following scenarios to the iSeries Information 
Center: 


To find_other information about what’s new or changed this release, see the|Memo 


4S 
How to see what’s new or changed 


To help you see where technical changes have been made, this information uses: 
* The 


oe 


image to mark where new or changed information begins. 
* The *& image to mark where new or changed information ends. 
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Chapter 3. Concepts 


Cryptography 


Cryptography is the art and science of keeping data secure. Basic cryptography 
services ensure that messages are private, that the integrity of a message is 
maintained, that the communicating parties are authenticated and that a party 
involved in a communication cannot refute having sent a message 


Cryptography allows you to store information or to communicate with other 
parties while preventing non-involved parties from understanding the stored 
information or understanding the communication. Encryption transforms 
understandable text into an unintelligible piece of data (ciphertext). Decrypting 
restores the understandable text from the unintelligible data. Both processes 
involve a mathematical formula or algorithm and secret data (the key). 


Cryptographic algorithms 


There are two types of cryptographic algorithms: 


1. With a secret or symmetric key algorithm, one key is a shared secret between 
two communicating parties. Encryption and decryption both use the same key. 
The Data Encryption Standard (DES) and Triple DES are examples of secret key 
algorithms. 


2. With a public key or asymmetric key algorithm, a pair of keys is used. One of 
keys, the private key, is kept secret and not shared with anyone. The other key, 
the public key, is not secret and is shared with anyone. When data is encrypted 
by one of the keys, it can only be decrypted and recovered by using the other 
key. The two keys are mathematically related, but it is virtually impossible to 
derive the private key from the public key. The RSA algorithm is an example of 
a public key algorithm. 


Both types of algorithms use keys to determine how to change the data. Different 
cryptographic processes use an algorithm to achieve one of several purposes. You 
choose the cryptographic process to use depending on the purpose, for example 
generating a message authentication code (MAC) to ensure data integrity. A 
user-written application for the 4758 Cryptographic Coprocessor calls the 
cryptographic process by using the corresponding security application 
programming interface (SAPI). Together the key and cryptographic process 
transform the data. A user with authorization to the SAPI has access to that 
cryptographic process. Therefore, the key controls access to the data. You must 
safeguard the keys to protect the data. If you keep the key value secret, you ensure 
the security of your data with each use of the algorithm with the key. 


Encryption 


With field level encryption, the user application explicitly requests cryptographic 
services. The user application completely controls key generation, selection, and 
distribution. The user application also controls what data to encrypt and what data 
to keep as plain-text. With encryption at the session layer, the system is requesting 
cryptographic services instead of your application. Your application may or may 
not be aware that encryption is happening. Link level encryption is performed at 
the lowest level of the protocol stack and usually by specialized hardware for that 
purpose. The 4758 Coprocessor supports both field level encryption and Secure 
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Sockets Layer (SSL) session establishment encryption, but not VPN or SNA session 
level encryption. The 2058 Cryptographic Acelerator only supports SSL session 
establishment encryption. 


Data integrity 


To rely on data, you need to know that it comes from an authorized source and is 
unchanged. This is known as data authenticity and data integrity. Your 4758 
Coprocessor can ensure authenticity and integrity by creating a Message 
Authentication Code (MAC), a message digest, or a digital signature. 


Message Authentication Code (MAC) 


The MAC process is a data integrity technique in which you define critical data 
elements. For example, you could define the amount in a funds transfer message. 
The critical data elements, cryptographic algorithm, and secret MAC key generate 
the MAC. The MAC becomes part of the message and travels with it. The MAC 
process uses DES or Triple DES keys. 


The receiver of the message uses the same MAC key, algorithm, and procedure as 
the sender to reproduce the MAC. If the receiver’s MAC matches the MAC sent 
with the message, they can accept the MAC as unaltered. 


The MAC process helps authenticate received messages, but does not prevent 
unauthorized reading because the transmitted data remains as plaintext. By using 
the MAC process and then encrypting the entire message, you can more effectively 
protect both data privacy and integrity. 


Message digest 


A message digest process can be performed on data to produce a digest value 
which can be thought of as a cryptographically generated checksum. If any portion 
of the data is modified, a different digest would be generated. You can keep copies 
of message digests, and compare them. Message digests that are identical indicate 
that no data has been modified. 


Digital signature 


A digital signature can also be used to verify authenticity and integrity. It is a two 
step process: 


1. First a digest is generated from the data and then the digest is encrypted using 
a private RSA key. The result is a digital signature. The signature can be 
verified by decrypting the signature using the public key to recover the original 
digest. 


2. Another digest is generated from the data and is compared to the original 
digest. If the two are identical, then the signature is validated and you can be 
confident that the data has not been altered. 


Key types associated with the 4758 Cryptographic Coprocessor 
Your 4758 Coprocessor uses various key types. Not all DES or Triple DES 
keys can be used for all symmetric key operations. Likewise, not all public 
key algorithm (PKA) keys can be used for all asymmetric key operations. 
This is a list of the various key types which the 4758 Coprocessor uses: 


Master key 
This is a clear key, which means that no other key encrypted it. 
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The 4758 Coprocessor uses the master key to encrypt all 
operational keys. The 4758 Coprocessor stores the master key in a 
tamper-responding module. You cannot retrieve the master key 
from the 4758 Coprocessor. The 4758 Coprocessor responds to 
tamper attempts by destroying the master key and destroying its 
factory certification. The 4758-023 has two master keys: one for 
encrypting DES keys and one for encrypting PKA keys. 


Double-length key-encrypting keys 
Your 4758 Coprocessor uses this type of Triple-DES key to encrypt 
or decrypt other DES or Triple DES keys. Key-encrypting-keys are 
generally used to transport keys between systems. However, they 
can also be used for storing keys offline for backup. If 
key-encrypting-keys are used to transport keys, the clear value of 
the key-encrypting-key itself must be shared between the two 
systems. Exporter key-encrypting keys are used for export 
operations where a key encrypted under the master key is 
decrypted and then encrypted under the key-encrypting key. 
Importer key-encrypting keys are used for import operations where 
a key encrypted under the key-encrypting key is decrypted and 
then encrypted under the master key. 


Double-length PIN keys 
Your 4758 Coprocessor uses this type of key to generate, verify, 
encrypt, and decrypt PINs used in financial operations. These are 
Triple DES keys. 


MAC keys 
Your 4758 Coprocessor uses this type of key to generate Message 
Authentication Codes (MAC). These can be either DES or Triple 
DES keys. 


Cipher keys 
Your 4758 Coprocessor uses this type of key to encrypt or decrypt 
data. These can be either DES or Triple DES keys. 


Single-length compatibility keys 
Your 4758 Coprocessor uses this type of key to encrypt or decrypt 
data and generate MACs. These are DES keys and are often used 
when encrypted data or MACs are exchanged with systems that do 
not implement the Common Cryptographic Architecture. 


Private keys 
Your 4758 Coprocessor uses private keys for generating digital 
signatures and for decrypting DES or Triple DES keys encrypted 
by the public key. 


Public keys 
Your 4758 Coprocessor uses public keys for verifying digital 
signatures, for encrypting DES or Triple DES keys, and for 
decrypting data encrypted by the private key. 


Key forms 
The 4758 Coprocessor works with keys in one of four different forms. The 
key form, along with the key type, determines how a cryptographic 
process uses that key. The four forms are: 


Clear form 
The clear value of the key is not protected by any cryptographic 
means. Clear keys are not usable by the 4758 Coprocessor. The 
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clear keys must first be imported into the secure module and 
encrypted under the master key and then stored outside the secure 
module. 


Operational form 
Keys encrypted under the master key are in operational form. They 
are directly usable for cryptographic operations by the 4758 
Coprocessor. Operational keys are also called internal keys. All 
keys that are stored in the server key store file are operational 
keys. However, you do not need to store all operational keys in the 
key store file. 


Export form 
Keys encrypted under an exporter key-encrypting key as the result 
of an export operation are in export form. These keys are also 
called external keys. A key in export form can also be described as 
being in import form if an importer key-encrypting key with the 
same clear key value as the exporter key-encrypting key is present. 
You may store keys in export form in any manner that you choose, 
however, you can not store them in key store files. 


Import form 
Keys encrypted under an importer key-encrypting key are in 
import form. Only keys in import form can be used as the source 
for an import operation. These keys are also called external keys. A 
key in import form can also be described as being in export form if 
an exporter key-encrypting key with the same clear key value as 
the importer key-encrypting key is present. You may store keys in 
import form in any manner that you choose, however, you can not 
store them in key store files. 


Function control vector 
IBM provides a digitally signed value known as a function control vector. 
This value enables the cryptographic application within the 4758 
Coprocessor to yield a level of cryptographic service consistent with 
applicable import regulations and export regulations. The function control 
vector is shipped with the IBM Cryptographic Access Provider (5722—ACx) 
product you install on your system. The path name of the file is 
/QIBM/ProdData/CAP/FCV.CRT. The function control vector provides 
your 4758 Coprocessor with the key length information necessary to create 
keys. 


Control vectors 
A control vector, different from a function control vector, is a known value 
associated with a key that governs the following: 


* Key type 

¢ What other keys this key can encrypt 

* Whether your 4758 Coprocessor can export this key 
* Other allowed uses for this key 


The control vector is cryptographically linked to a key and can not be 
changed without changing the value of the key at the same time. 


Key store file 
An OS/400 database file that is used to store keys which you encrypted 
under the master key of the 4758 Coprocessor. 


Key token 
A data structure that can contain a cryptographic key, a control vector, and 
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other information related to the key. Key tokens are used as parameters on 
most of the CCA API verbs that either act on or use keys. 


Chapter 3. Concepts 11 


12 iSeries: Cryptographic hardware 


Chapter 4. 4758 Cryptographic Coprocessor for iSeries 


With iSeries servers, you can use the 4758 Coprocessor in the following ways: 


* You can use the 4758-023 Coprocessor along with DCM to generate and store 
private keys associated with SSL digital certificates. In addition the 4758-023 
Coprocessor provides a performance assist enhancement and capability by 
handling SSL private key processing during SSL session establishment. 


* In order to support load balancing and performance scaling, the iSeries server 
allows the usage of multiple (up to eight) 4758-023 Coprocessors with SSL. 
When using multiple Coprocessors, DCM configuration gives you the following 
options for using hardware to generate and store the private key associated with 
a digital certificate. 


1. Private key generated in hardware and stored (i.e., retained) in hardware. 


With this option the private key never leaves the Coprocessor, and thus the 
private key cannot be used or shared with another Coprocessor. This means 
that you and your application have to manage multiple private keys and 
certificates. 


2. Private key generated in hardware and stored in software (i.e., stored in a 
key store file). 


This option allows a single private key to be shared amongst multiple 
Coprocessors. A requirement is that each Coprocessor must share the same 
master key—you can use F Clonemnastetkeye" oh page 10a set up your 
Coprocessors to have the same master key. The private key is generated in 
one of the Coprocessors and is then saved in the key store file, encrypted 


under the master key of that Coprocessor. Any Coprocessor with an identical 
master key can use that private key. 


* You can use the 4758-023 Coprocessor to implement OS/400 applications. To do 
this you or an applications provider must write an application program, using 
the CCA CSP APIs to access the cryptographic services in the 4758 Coprocessor. 
Examples of such applications are financial PIN processing transactions, bank to 
clearing house transactions, and basic SET™ block processing. Up to eight 
Coprocessors can be used via the CCA CSP. The application must control access 
to individual Coprocessor by using the Cryptographic_Resource_Allocate 
(CSUACRA) and Cryptographic_Resource_Deallocate (CSUACRD) CCA APIs. 


For more information about your 4758 Coprocessor, refer to the following pages: 


“Features of the 4758 Cryptographic Coprocessor” on page 14 


The 4758 Coprocessor contains hardware engines, which perform cryptographic 
operations used during SSL and OS/400 applications. 


The Common Cryptographic Architecture Cryptographic Service Provider (CCA 
CSP) is packaged as OS/400 Option 35. It provides a security application 
programming interface (SAPI) to which you can write applications that allow you 
to access the cryptographic services of your 4758 Coprocessor. 


The features page describes in greater detail what the 4758 Coprocessor and CCA 
CSP have to offer. 


“Requirements for the 4758 Cryptographic Coprocessor” on page 19 
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Your server must meet some requirements before you can install and use your 4758 
Coprocessor. Use the requirements page to determine whether you are ready to 
install and use your 4758 Coprocessor on your server. 


Chapter 3, “Concepts” on page 7 


Depending on your familiarity with cryptography, you may need more information 
about a term or concept. This page introduces you to some basic cryptographic 
concepts. 


See |Related information| for additional sources of cryptography information 


recommended by IBM. 


Features of the 4758 Cryptographic Coprocessor 


14 


The 4758 PCI Cryptographic Coprocessor provides cryptographic processing 
capability and secure storage of cryptographic keys. Cryptographic functions 
supported include encrypt/decrypt for keeping data confidential, message digests 
and message authentication codes for ensuring that data has not been changed, 
digital signature generate/verify, and financial PIN and SET processing. You can 
use the Coprocessor with OS/400 SSL or with OS/400 applications written by you 
or an application provider. 


When used with SSL, the Coprocessor can be used to create and store a private 
key in a FIPS 140-1 certified hardware module or the Coprocessor can be used to 
create, encrypt and store a private key (encrypted under the master key) in 
software so the private key can be used by multiple Coprocessor cards. Master 
keys are always stored in the FIPS 140-1 certified hardware module. Additionally, 
during the establishment of an SSL session the Coprocessor will off-load 
computationally-intensive cryptographic processing from the iSeries server main 
CPU. 


For OS/400 applications, the Common Cryptographic Architecture Cryptographic 
Service Provider (CCA CSP) APIs are used to access the cryptographic and key 
management functions of the Coprocessor. 


The 4758-023 PCI Cryptographic Coprocessor supports DES, triple-DES, RSA, MD5, 
SHA-1, RIPEMD-160, and financial PIN services. In addition, it supports SET 
(Secure Electronic Transaction) block cryptographic services. The main benefit of 
the 4758 Coprocessor is that it provides the capability to store encryption keys. It 
does this in a tamper-responding, battery backed-up module, which is also referred 
to as the secure module. The 4758-023 PCI Cryptographic Coprocessor the Federal 
Information Processing Standard (FIPS) PUB 1400-1, Level 3 requirements. Another 
benefit of the 4758 Coprocessor is that it can be used to off-load the iSeries server 
main CPU from computationally-intensive cryptographic processing during the 
establishment of a SSL session. 


The 4758 Coprocessor provides a role-based access control facility, which allows 
you to enable and control access to individual cryptographic operations supported 
by the Coprocessor. 


CCA CSP features 
You can use your 4758 Coprocessor with CCA CSP to provide high-level 


cryptographic security for your applications. Customer or third-party applications 
access these services through a set of application programming interfaces (APIs). 
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You can find these APIs described in the IBM 4758 PCI Cryptographic Coprocessor 
ICCA Basic Services Reference and Guide The APIs are provided with OS/400 
Option 35 - Common Cryptographic Architecture Cryptographic Service Provider 
(CCA CSP). 


The 4758 Coprocessor will use the CCA master key to encrypt keys so that you can 
store those keys outside of your 4758 Coprocessor. You store those keys in a key 
store file, which is a database file. 


IBM’s CCA enables a consistent approach to cryptography on major IBM 
computing platforms. OS/400 CCA CSP supports application software that is 
written in ILE C, RPG, and Cobol. Application software can call on CCA services 
to perform a wide range of cryptographic functions, including Data Encryption 
Standard (DES) and RSA algorithms. 


OS/400 CCA CSP provides API support equivalent to the CCA Support Program 
that is available for NT, AIX® and OS/2®. CCA CSP exploits the capabilities of the 
4758 Coprocessor and allows you to do the following: 


* Create role-based access controls to define the level of access that you give to 
your users. 


* Generate random-numbers. 

* Clone a master key securely. 

* Support financial PIN-processing. 

* Generate and validate digital signatures. 

* Encrypt and decrypt data. 

* Protect keys. 

* Import and export encrypted DES and Triple-DES keys securely. 
* Generate Message Authentication Codes (MAC). 


| Cryptographic hardware scenarios for the 4758 Cryptographic 


| Coprocessor 


a 


To give you some ideas of how you can use this cryptographic hardware with your 
iSeries server, we have added the following usage scenarios: 


This scenario might be useful for a company that needs to increase the security 
of the iSeries server server digital certificate private keys that are associated with 
the SSL-secured business transactions. 


See Coprocessor 


This scenario could help an OS/400 programmer reason through the process of 
writing a program that calls the 4758 Cryptographic Coprocessor to verify user 
data such as financial personal identification numbers (PINs), which are entered 


at automatic teller machines (ATMs).*& 
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Situation 


Details 


Cryptographic hardware scenario: Protect private keys with 
cryptographic hardware 


a 


A company has an iSeries server dedicated to handling business-to-business (B2B) 
transactions. This company’s iSeries server specialist, Sam, has been informed by 
management of a security requirement from its B2B customers. The requirement is 
to increase the security of the iSeries server digital certificate private keys that are 
associated with the SSL-secured business transactions that Sam’s company 
performs. Sam has heard that there is a cryptographic hardware option available 
for iSeries servers that both encrypts and stores private keys associated with SSL 
transactions in tamper-responding hardware: The IBM 4758-023 Cryptographic 
Coprocessor PCI card (Hardware Feature code 4801, or 4802, and hereafter referred 
to as the 4758 Cryptographic Coprocessor). 


Sam researches the 4758 Cryptographic Coprocessor, and learns that he can use it 
with the OS/400 Digital Certificate Manager (DCM) to provide secure SSL private 
key storage, as well as increase iSeries server performance by off-loading from the 
iSeries server the cryptographic operations which are completed during 
SSL-session establishment. 


Note: To support load balancing and performance scaling, Sam can use multiple 
(up to eight) 4758 Cryptographic Coprocessors with SSL on the iSeries 


server. See [Implementing multiple cryptographic hardware cards on the 


iSeries] for more information. 


Sam decides that the 4758 Cryptographic Coprocessor meets his company’s 
requirement to increase the security of his company’s iSeries server. 


1. The company’s iSeries server has a 4758 Cryptographic Coprocessor installed 
and configured to store and protect private keys. 


2. Private keys are generated by the 4758 Cryptographic Coprocessor. 


o 


Private keys are then stored on the 4758 Cryptographic Coprocessor. 


4. The 4758 Cryptographic Coprocessor resists both physical and electronic 
hacking attempts. 


Prerequisites and assumptions 


1. The iSeries server has a 4758 Cryptographic Coprocessor installed and 


configured properly (see|Plan for the 4758 Cryptographic Coprocessor} and 
Configure the 4758 Cryptographic Coprocessor). Planning for the 4758 


Cryptographic Coprocessor includes getting SSL running on the iSeries server. 


Note: To use multiple 4758 Cryptographic Coprocessor cards for application 
SSL handshake processing, and securing private keys, Sam will need to 
ensure that his application can manage multiple private keys and 
certificates. 
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Configuration steps 


2. Sam’s company has Digital Certificate Manager (DCM) installed and 
configured, and _uses it to|Manage public Internet certificates for SSL 
3. Sam’s company obtain certificates from a public Certificate Authority (CA). 


4. The 4758 Cryptographic Coprocessor is varied on prior to using DCM. 
Otherwise, DCM will not provide a page for selecting a storage option as part 
of the certificate creation process. 


Sam needs to perform the following steps to secure private keys with 
cryptographic hardware on his company’s iSeries server: 
1. Ensure that the prerequisites and assumptions for this scenario have been met. 
2. Use the IBM Digital Certificate Manager (DCM) to create a new digital 
certificate, or renew a current digital certificate: 
a. Select the type of certificate authority (CA) that is signing the current 
certificate. 
b. Select the Hardware as your storage option for certificate’s private key. 
c. Select which cryptographic hardware device you want to store the 
certificate’s private key on. 
d. Select a public CA to use. 


The private key associated with the new digital certificate is now stored on the 
4758 Cryptographic Coprocessor specified in Step 2.c. Sam can now go into the 
configuration for his company’s web server and specify that the newly created 
certificate be used. Once he restarts the web server, it will be using the new 


certificate.%& 


Cryptographic hardware scenario: Write an OS/400 application 
to use the 4758 Cryptographic Coprocessor 


Situation 


a 


Suppose you are an iSeries server programmer for a large financial Credit Union. 
You have been assigned the task of getting the IBM 4758-023 Cryptographic 
Coprocessor PCI card (Hardware Feature code 4801 or 4802, and hereafter referred 
to as the 4758 Cryptographic Coprocessor) that is installed in the Credit Union 
iSeries server to verify members’ financial personal identification numbers (PINs) 
when they are entered at automatic teller machines (ATMs). 


You decide to write an iSeries server OS/400 application program using the CCA 
CSP (cryptographic service provider) APIs that are a part of Option 35 to access 
the cryptographic services in the 4758 Coprocessor to verify members’ PINs. iSeries 
server OS/400 application programs written for the 4758 Cryptographic 
Coprocessor utilize the coprocessor to perform security-sensitive tasks and 
cryptographic operations. 


Note: Up to eight 4758 Cryptographic Coprocessors can be used via the CCA CSP. 
The application must control access to individual Coprocessor by using the 
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Details 


Cryptographic_Resource_Allocate (CSUACRA) and 
Cryptographic_Resource_Deallocate (CSUACRD) CCA APIs. 


1. A Credit Union member enters their PIN at an ATM. 


The PIN is encrypted at the ATM, and then sent along the network to the 
Credit Union’s iSeries server. 


The iSeries server recognizes the transaction request, and calls a program to 
verify the member’s PIN. 


The program sends a request containing the encrypted PIN, member’s account 
number, PIN-generating key, and PIN encrypting key to the 4758 Cryptographic 
Coprocessor. 


The 4758 Cryptographic Coprocessor confirms or denies the validity of the PIN. 

The program sends the 4758 Cryptographic Coprocessor’s results to the ATM. 

a. If the PIN is confirmed, the member can successfully complete a transaction 
with the Credit Union. 

b. If the PIN is denied, the member is unable to complete a transaction with 
the Credit Union. 


Prerequisites and assumptions 


Configuration steps 


1. 


Your company has an iSeries server with a properly installed and configured 
4758 Cryptographic Coprocessor. Refer to the following information: 


a. |Plan for the 4758 Cryptographic Coprocessor 
b. {Configure the 4758 Cryptographic Coprocessor 
c. |Configure the 4758 Cryptographic Coprocessor for use with OS/400 


You are familiar with Option 35: The Common Cryptographic Architecture 
Cryptographic Service Provider (CCA CSP). It is packaged as OS/400 Option 
35, and provides a security application programming interface (SAPI) to which 
you can write applications that allow you to access the cryptographic services 
of the 4758 Cryptographic Coprocessor. 


You have access to the |CCA Basic Services Guide ad , where you can find 


Financial Services Support verbs to use in your application. 


One way to accomplish your objective of using the 4758 Cryptographic 
Coprocessor to validate PINs is to write two iSeries server OS/400 applications: 


1. 


Write a program that loads the both the PIN verification keys, and PIN 
encrypting keys, and stores them in a key store file. Assuming that clear key 
parts are used, you need to use the following APIs: 


* Logon_Control (CSUALCT) 

* Key_Part_Import (CSNBKPI) 

* Key_Token_Build (CSNBKTB) 

* Key_Record_Create (CSNBKRC) 

* Key_Record_Write (CSNBKRW) 

* Optional API: KeyStore_Designate (CSUAKSD) 
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2. Write a second program that calls the Encrypted_PIN_Verify (CSNBPVR) API to 
verify encrypted PINs, and then reports their valid or invalid status back to the 
ATM. 


Related page: {Configure the 4758 Cryptographic Coprocessor for use with OS/400 
Bpplicationsk 


Plan for the 4758 Cryptographic Coprocessor 


The following information is pertinent to those planning to install a 4758 
Cryptographic Coprocessor in an iSeries server: 


* [Requirements for the 4758 Cryptographic Coprocessor 
* [Secure access to the 4758 Cryptographic Coprocessor 
* |Object authorities that are required for SAPI 


Requirements for the 4758 Cryptographic Coprocessor 


Your server must meet these requirements before you install and use the 4758 
Coprocessor. 


Hardware requirements 


The 4758-023 Coprocessor for iSeries server can be ordered by specifying feature 
code 4801 or 4802. The 4801 feature is supported on the following iSeries server 
models: 

* 250 and 270 (250 requires the 7102 expansion unit) 

* 810, 820, 825, 830, 840, 870 and 890 

* SB2 and SB3 

* Expansion units 5074, 5075, 5078, 5079, 5088, 5094, 5095 and 5294 


Your 4758 Coprocessor is a PCI card. Install the card as described in the 
installation manual that came with your Coprocessor. 


Note: The 4758 Coprocessor destroys its factory certification if allowed to cool 
below -15 degrees C (5 degrees F). If your 4758 Coprocessor destroys its factory 
certification, you can no longer use the card. Contact your hardware service 
provider about ordering a new card. 


Software requirements 


Your 4758 Coprocessor requires the following software: 

* OS/400 (5722-551): the 4758-023 Coprocessor (iSeries server feature codes 4801 
or 4802) requires OS/400 Version 4 Release 5 Modification 0 or later. 

* OS/400 Option 35 Common Cryptographic Architecture Cryptographic Service 
Provider (CCA CSP) 

* OS/400 Option 34 Digital Certificate Manager (if you are planning on using 4758 
Coprocessor configuration web-based utility) 

* OS/400 57xx-TC1 TCP/IP Connectivity Utilities (if you are planning on using 
4758 Coprocessor configuration web-based utility) 

* OS/400 57xx-DG1 IBM HTTP Server (if you are planning on using 4758 
Coprocessor configuration web-based utility) 


* The Cryptographic Access Provider 128-bit for iSeries server (5722-AC3) licensed 
program product must be installed on your iSeries server to enable the 


Chapter 4. 4758 Cryptographic Coprocessor for iSeries 19 


20 


encryption capabilities of the 4758 Cryptographic Coprocessor. This option 
enables your 4758 Coprocessor to use 56-bit DES keys, 112 bit Triple DES keys, 
and 2048-bit RSA keys. 


Notes: 


1. The 4758 Coprocessor configuration web-based utility was new with OS/400 
Version 5 Release 2 Modification 0. 


2. Special, limited availability PTFs must be installed before using the 4758-023 
Coprocessor with SSL on OS/400 Version 4 Release 5 Modification 0. No special 
PTFs are required to use the 4758-023 Coprocessor with SSL on OS/400 Version 
5 Release 2 Modification 0, or later releases of OS/400. 


3. You may have a previous version of a Cryptographic Access Provider (e.g. 
5769-AC1, 5769-AC2, 5769-AC3) installed. These products are compatible with 
Version 5 Release 2 Modification 0. 


Secure access to the 4758 Cryptographic Coprocessor 


Access control restricts the availability of system resources to only those users you 
have authorized to interact with the resources. The server allows you to control 
authorization of users to system resources. Your organization should identify each 
system resource in the organization’s security hierarchy. The hierarchy should 
clearly delineate the levels of access authorization users have to resources. 


All of the service programs in OS/400 Option 35 are shipped with *EXCLUDE 
authority for *PUBLIC. You must give users *USE authority for the service 
program that they need to use. In addition, you must also give users *USE 
authority to the QC6SRV service program in library QCCA. 


Users who take part in setting up the 4758 Coprocessor must have *IOSYSCFG 
special authority to use the Master_Key_Process (CSNBMKP), 
Access_Control_Initialize (CSUAACT), or Cryptographic_Facility_Control 
(CSUACFC) security application programming interfaces (SAPIs). These three 


SAPIs are used to perform all configuration steps for the 4758 Coprocessor. For all 
SAPIs, users may require additional object authorities. Refer tol"Object authorities 
For the most secure environments, consider assigning the role of 4758 
administrators to a set of users who do not have *ALLOBJ special authority. This 
way, users with *ALLOBJ special authority cannot alter the configuration of the 
Coprocessor because they will not be able to log on to an administrative role on 


the 4758. They can, however, control object authority to the SAPI service programs, 
preventing misuse by the 4758 administrators. 


In order to use the 4758 Cryptographic Coprocessor configuration web utility, users 
must have *SECADM special authority. 


The 4758 Coprocessor has separate access controls which are unrelated to the 
access controls of the server. The 4758 Coprocessor access controls allow you to 


control access to the 4758 Coprocessor hardware commands. For more information 
about these commands, see |“Create and define roles and profiles” on page 25 

For even more security, limit the capabilities of the default role within your 4758 
Coprocessor. Assign capabilities among other roles to require two or more people 


to perform security-sensitive functions, like changing the master key. You can do 
this when you work with roles and profiles as described in [Create and define 
roles and profiles” on page 25) 
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Note: You should consider some standard physical security measures as well, such 


as keeping your server behind a locked door. 


Object authorities that are required for SAPI 


SAPI *USE for |*USE for |*CHANGE*USE for |*USE for |*CHANGE*USE for 
device DES for DES |DES PKA for PKA |PKA 
keystore | keystore |Keystore | keystore | keystore | Keystore 
Library Library 
CSNBCKI_ | Y Y¥" Y? 
CSNBCKM+*| Y x Y 
CSNBCPA |Y Y¥* Xe 
CSNBCPE | Y y! y! 
CSNBCSG? | Y y! y! 
CSNBCSV* | Y x Y" 
CSNBCVE? | Y Ye y! 
CSNBCVG* 
CSNBCVT? | Y Y* Y? 
CSNBDEC | Y y! Y: 
CSNBDKG | Y y! Me 
CSNBDKM | Y Y% ¥* y! 
CSNBDKX | Y y¥* y 
CSNBENC |Y yt NG 
CSNBEPG |Y y! y? 
CSNBKEX | Y y! Y? 
CSNBKGN | Y xX ¥* y! 
CSNBKPI | Y y! y! 
CSNBKRC | Y Y Y 
CSNBKRD | Y Y Y 
CSNBKRL | Y Y x 
CSNBKRR | Y Y x 
CSNBKRW | Y Y x 
CSNBKSI | Y Y? y= ¥? ¥? 
CSNBKTC |Y Y! y! 
CSNBKTP* 
CSNBKTR | Y y! y! 
CSNBKYT |Y Y* Y* 
CSNBMDG4 Y 
CSNBMGN | Y y! y! 
CSNBMKP | Y 
CSNBOWH 
CSNBPEX?* | Y Y? y" 
CSNBPGN | Y y! Y? 
CSNBPTR |Y y! y! 
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SAPI *USE for |*USE for |*CHANGE*USE for |*USE for |*CHANGE*USE for 
device DES for DES |DES PKA for PKA |PKA 
keystore | keystore |Keystore | keystore | keystore | Keystore 
Library Library 
CSNBPVR | Y y? ¥ 
CSNBTRW*| Y Y Y 
CSNDDSG | Y x y! 
CSNDDSV |Y y! y? 
CSNDKRC Y Y 
CSNDKRD Y Y 
CSNDKRL Y Y 
CSNDKRR Y Y 
CSNDKRW Y Y 
CSNDKTC |Y y! x 
CSNDPKB?* 
CSNDPKG | Y AG y! ¥? 
CSNDPKH | Y 
CSNDPKI | Y x" y! y? 
CSNDPKR | Y 
CSNDPKX | Y y? y! 
CSNDRKD | Y 
CSNDRKL | Y 
CSNDSBC |Y x xe 
CSNDSBD | Y y? Y? 
CSNDSYG |Y Xe a 
CSNDSYI | Y y! Y? x? yx" 
CSNDSYX | Y Xe Y y? ¥- 
CSUAACI |Y 
CSUAACM | Y 
CSUACFC |Y 
CSUACFQ |Y 
CSUACRA |Y 
CSUACRD | Y 
CSUAKSD 
CSUALCT |Y 
CSUAMKD | Y 


Use of Data Encryption Standard (DES) or public key algorithm (PKA) keystore 
for this API is optional. 


*More than one parameter may optionally use keystore. The authority 
requirements differ on each of those parameters. 
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°The Key_Store_Initialize SAPI does not require authority to both files 
simultaneously. 


“These SAPIs pertain only to the 4758-023 Coprocessor. 


Configure the 4758 Cryptographic Coprocessor 


Configuring your 4758 Coprocessor allows you to begin to use all of its 
cryptographic operations. 


The easiest and fastest way to configure your 4758 Coprocessor is to use the 4758 
Cryptographic Coprocessor configuration web-based utility found off of the iSeries 
server Tasks page at http://server-name:2001. The utility includes the Basic 
configuration wizard that is used for configuring (and initializing) a Coprocessor 
that has not been previously configured. If HTTP and SSL have not been 
previously configured, you will need to do the following before using the 
Configuration Wizard. 


* Start the HTTP Administrative server. 
* Configure the HTTP Administrative server to use SSL. 


* Use DCM to create a certificate, specifying that the private key be generated and 
stored in software. 


* Use DCM to receive the signed certificate. 
* Associate the certificate with the HTTP Administrative server application ID. 
* Re-start the HTTP Administrative server to enable it for SSL processing. 


If the 4758 Coprocessor has already been configured, then click on the Manage 
configuration option to change the configuration for specific portions of the 
Coprocessor. 


If you would prefer to write your own application to configure the Coprocessor, 
you can do so by using the Cryptographic_Facility_Control (CSUACFC), 
Access_Control_Initialize (CSUAACT), Master_Key_Process (CSNBMKP), and 
Key_Store_Initialize (CSNBKSI) API verbs. Many of the pages in this section 
include one or more program examples that show how to configure the 
Coprocessor via an application. Change these programs to suit your specific needs. 


Whether you choose to use the 4758 Cryptographic Coprocessor configuration 
utility or write your own applications, the following outlines the steps you must 
take to properly configure your 4758 Coprocessor: 


1. |“Create a device description” on page 24} The device description specifies a 


default location for key storage. You can create a device description with or 
without naming any key store files. 


2. |“Name files to key store file” on page 25] Before you can perform any operation 


using a key store file or key stored in a key store file, you must name the key 
store file. You can explicitly name key store files by using a program, or you 
can name them on the device description. You name one file to store Data 
Encryption Standard (DES) and Triple-DES keys and another file to store public 
key algorithm (PKA) keys. By naming the files in which to store your keys, you 
set up that database to contain your DES (and Triple-DES) and PKA keys. You 
should name key store files by using a program if you want to keep your keys 
in your own key store file. If you do not name key store files with a program, 
the CCA CSP will store your keys in the key store file named on the device 
description. 
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3. |“Create and define roles and profiles” on page 25| When you assign users to 


these roles and profiles, you determine what cryptographic functions your 4758 
Coprocessor will allow the users to use. 


4. |“Set the environment ID and clock” on page 63} Your 4758 Coprocessor uses the 


EID to verify which 4758 Coprocessor created a key token. It uses the clock for 
time and date stamping and to control whether a profile can log on. 


5. |“Load a function control vector” on page 74] The function control vector tells 
the 4758 Coprocessor what key length to use to create keys. You cannot 
perform any cryptographic functions without loading a function control vector. 


6. |“Load and set a master key” on page 86] After you load a function control 


vector, load and set the master key. You can use your master key to encrypt 
other keys. 


Create a device description 


You must create a device description for your 4758 Coprocessor on your server. 
The device description is used by CCA CSP to help direct cryptographic requests 
to the 4758 Coprocessor. Additionally, the device description gives your 4758 
Coprocessor a default location for key store file storage. The Basic configuration 
wizard in the 4758 Cryptographic Coprocessor configuration utility, found off of 
the iSeries server Tasks page at http://server-name:2001, can create a device 
description for you, or you can create a device description yourself by using the 
Create Device Crypto CL command. 


To create a device description using the Basic configuration wizard, follow these 
steps: 


1. Point your web browser to the iSeries server Tasks page: http://server- 
name : 2001 


Click on 4758 Cryptographic Coprocessor configuration. 
Click on the button labeled Start secure session. 

Click Basic configuration wizard. 

Click continue on the Welcome page. 


A2aRON 


Click on the list entry with the device name set to *CREATE for the resource you 
want to use. 


7. Continue as instructed by the Basic configuration wizard. 


To create a device description using the CL command, follow these steps: 

1. Type CRTDEVCRP at the CL command line. 

2. Specify a name for the device as prompted. If you want to set up a default 
device, name the device CRP01. Otherwise, each application you create must 
use the Cryptographic Resource Allocate (CSUACRA) API in order to access 
your device description. 


3. Specify the name of a default PKA key store file or let the parameter default to 
*NONE. 


4. Specify the name of a default DES key store file or let the parameter default to 
*NONE. 

5. Specify a description as prompted. This is optional. 

6. Use either the Vary Configuration (VRYCFG) or the Work with Configuration 
Status (WRKCFGSTS) CL commands to vary on the device once you have 
created the device description. 


7. This typically takes one minute, but it may take ten minutes to complete. 
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You have now completed creation of the device description. 


Name files to key store file 


Before you can perform any operation using a key store file or a key stored in a 
key store file, you must name the key file. This points your 4758 Coprocessor to 
the correct file. You can name two types of key store files. One type stores Data 
Encryption Standard (DES) keys and Triple-DES keys. DES and Triple DES are 
symmetric cryptographic algorithms; the 4758 Coprocessor uses the same key to 
encrypt and decrypt. The other type stores public key algorithm (PKA) keys. 
Public key algorithms are asymmetric; keys are created in pairs. The 4758 
Coprocessor uses one key to encrypt and the other to decrypt. The 4758 
Coprocessor supports the RSA public key algorithm. 


You can name a key store file explicitly by using a program, or you can name it by 
configuring it on the device description. To name a key store file from a program, 
use the Key_Store_Designate (CSUKSD) security application programming 
interface (SAPI). If you name key store files that use a program, your 4758 
Coprocessor only uses the names for the job that ran the program. However, by 
naming key store files explicitly in your program, you can use separate key store 
files from other users. If you name key store files on the device description, you do 
not have to name them in your program. This may help if you are trying to 
maintain the same program source across multiple IBM platforms. It is also useful 
if you are porting a program from another implementation of Common 
Cryptographic Architecture. 


You need to store your cryptographic keys in a secure form so that you can use 
them over time and exchange them with other users and servers, as appropriate. 
You can store your cryptographic keys by using your own methods, or you can 
store them in a key store file. You can have as many key store files as you want, 
and you can create multiple key store files for each type of key. You can place as 
many cryptographic keys in your key store files as you want. 


Since each key store file is a separate server object, you can authorize different 
users to each file. You can save and restore each key store file at different times. 
This depends on how often the file’s data changes or which data it is protecting. 


Create and define roles and profiles 


The 4758 Coprocessor uses role-based access control. In a role-based system, you 
define a set of roles, which correspond to the classes of 4758 Coprocessor users. 
You can enroll each user by defining an associated user profile to map the user to 
one of the available roles. 


The capabilities of a role are dependent on the access control points or 
cryptographic hardware commands that are enabled for that role. You can then use 
your 4758 Coprocessor to create profiles that are based on the role you choose. 


A role-based system is more efficient than one in which the authority is assigned 
individually for each user. In general, you can separate the users into just a few 
different categories of access rights. The use of roles allows you to define each of 
these categories just once, in the form of a role. 


The role-based access control system and the grouping of permissible commands 
that you can use are designed to support a variety of security policies. In 
particular, you can set up the 4758 Coprocessor to enforce a dual-control, 
split-knowledge policy. Under this policy no one person should be able to cause 
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detrimental actions other than a denial-of-service attack, once the 4758 Coprocesor 
is fully activated. To implement this policy, and many other approaches, you need 
to limit your use of certain commands. As you design your application, consider 
the commands you must enable or restrict in the access-control system and the 
implications to your security policy. 


Every 4758 Coprocessor must have a role called the default role. Any user that has 
not logged on to the 4758 Coprocessor will operate with the capabilities defined in 
the default role. Users who only need the capabilities defined in the default role do 
not need a profile. In most applications, the majority of the users will operate 
under the default role, and will not have user profiles. Typically, only security 
officers and other special users need profiles. 


When the 4758 Coprocessor is in an uninitialized state, the default role has the 
following access control points enabled: 


* PKA96 One Way Hash 

* Set Clock 

* Reinitialize Device 

* Initialize access control system roles and profiles 
* Change the expiration data in a user profile 

* Reset the logon failure count in a user profile 

* Read public access control information 

* Delete a user profile 

* Delete a role 


The default role is initially defined such that the functions permitted are those 
functions that are related to access control initialization. This guarantees that the 
4758 Coprocessor will be initialized before you do any useful cryptographic work. 
The requirement prevents security “accidents” in which someone might 
accidentally leave authority intact when you put the 4758 Coprocessor into service. 


Defining roles 


The easiest and fastest way to define new roles (and re-define the default role) is to 
use the 4758 Cryptographic Coprocessor configuration web-based utility found off 
of the iSeries server Tasks page at http://server-name:2001. The utility includes the 
Basic configuration wizard that is used when the Coprocessor is in an uninitialized 
state. The Basic configuration wizard can define either 1 or 3 administrative roles 
along with re-defining the default role. If the 4758 Coprocessor already has been 
initialized, then click on Manage configuration and then click on Roles to define 
new roles or change or delete existing ones. 


If you would prefer to write your own application to manage roles, you can do so 
by using the Access_Control_Initialization (CSUAACI) and 
Access_Control_Maintenance (CSUAACM) API verbs. To change the default role in 
your 4758 Coprocessor, specify "DEFAULT" encoded in ASCII into the proper 
parameter. You must pad this with one ASCII space character. Otherwise, there are 
no restrictions on the characters that you may use for role IDs or profile IDs. Four 
example programs are provided for your consideration. Two of them are written in 
ILE C, while the other two are written in ILE RPG. Both sets perform the same 
function. 


“Example: ILE C program for creating roles and profiles for your 4758 


Coprocessor” on page 30 
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° |“Example: ILE C program for enabling all access control points in the default 
role for your 4758 Coprocessor” on page 50 


“Example: ILE RPG program for creating roles or profiles for your 4758 


Coprocessor” on page 41 


“Example: ILE RPG program for enabling all access control points in the default 


role for your 4758 Coprocessor” on page 55 


Note: If you choose to use one of the program examples provided, change it to 
suit your specific needs. For security reasons, IBM recommends that you 
individualize these program examples rather than using the default values 
provided. 


Defining profiles 


After you create and define a role for your 4758 Coprocessor, you can create a 
profile to use under this role. A profile allows users to access specific functions for 
your 4758 Coprocessor that may not be enabled for the default role. 


The easiest and fastest way to define new profiles is to use the 4758 Cryptographic 
Coprocessor configuration web-based utility, located on the iSeries server Tasks 
page at http://server-name:2001. The utility includes the Basic configuration 
wizard that is used when the Coprocessor is in an uninitialized state. The Basic 
configuration wizard can define either one or three administrative profiles. If the 
4758 Coprocessor has already been initialized, click Manage 
configuration—>Profiles to define new profiles or change or delete existing ones. 


If you want to write your own application to manage profiles, you can use the 
Access_Control_Initialization (CSUAACI) and Access_Control_Maintenance 
(CSUAACM) API verbs. Two example programs are provided for you: 


Coprocessor” on page 60 


Note: If you choose to use one of the program examples provided, change it to 
suit your specific needs. For security reasons, IBM recommends that you 
individualize these program examples rather than using the default values 
provided. 


If you will be using the 4758 Coprocessor for SSL, the default role must at least be 
authorized to the following access control points: 


* Digital Signature Generate 

* Digital Signature Verify 

* PKA Key Generate 

* PKA Clone Key Generate 

* RSA Encipher Clear Data 

* RSA Decipher Clear Data 

* Delete Retained Key 

* List Retain Keys 

The Basic configuration wizard in the 4758 Cryptographic Coprocessor 
configuration utility automatically re-defines the default role such that it can be 


used for SSL without any changes. 
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To avoid security hazards, consider denying the following access control points 
(also called cryptographic hardware commands) for the default role, after you have 
set up all of the roles and profiles: 


Note: You should enable only those access control points that are necessary for 
normal operations. At a maximum, you should only enable specifically 
required functions. To determine which access control points are required, 
refer to the CCA Basic Services Guide. Each API lists the access control 
points that are required for that API. If you do not need to use a particular 
API, consider disabling the access control points that are required for it. 


* Load first part of Master Key 

* Combine Master Key Parts 

* Set Master Key 

* Generate Random Master Key 

* Clear New Master Key Register 
* Clear Old Master Key Register 
* Translate CV 

* Set Clock 


Attention: If you intend to disable the Set Clock access control point from the 
default role, ensure that the clock is set before you disable access. The clock is 
used by the 4758 Coprocessor when users try to log on. If the clock is set 
incorrectly, users can not log on. 


* Reinitialize device 

* Initialize access control system 

* Change authentication data (for example, passphrase) 

* Reset password failure count 

* Read Public Access Control Information 

* Delete user profile 

* Delete role 

* Load Function Control Vector 

* Clear Function Control Vector 

* Force User Logoff 

* Set EID 

* Initialize Master Key Cloning Control 

* Register Public Key Hash 

* Register Public Key, with Cloning 

* Register Public Key 

* PKA Clone Key Generate (Access control point required for SSL) 
¢ Clone-Information Obtain Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
¢ Clone-Information Install Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
* Delete retained key (Access control point required for SSL) 

* List retained keys (Access control point required for SSL) 

* Encipher Under Master Key 

* Data Key Export 

* Data Key Import 

* Reencipher to Master Key 

* Reencipher from Master Key 
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* Load First Key Part 
* Combine Key Parts 
* Add Key Part 

* Complete Key part 


For the most secure environment, consider locking the access-control system after 
initializing it. You can render the access-control system unchangeable by deleting 
any profile that would allow use of the Access Control Initialization or the Delete 
Role acess control point. Without these access control points, further changes to 
any role are not possible. With authority to use either the Initialize Access Control 
or Delete Role access control points, one can delete the DEFAULT role. 


Deleting the DEFAULT role will cause the automatic recreation of the initial 
DEFAULT role. The initial DEFAULT role permits setting up any capabilities. Users 
with access to these access control points have unlimited authority through 
manipulation of the access-control system. Before the 4758 Coprocessor is put into 
normal operation, the access-control setup can be audited through the use of the 
Access_Control_Maintenance (CSUAACM) and Cryptographic_Facility_Query 
(CSUACFQ) API verbs. 


If for any reason the status response is not as anticipated, the 4758 Coprocessor 
should not be used for application purposes until it has been configured again to 
match your security policy. If a role contains permission to change a passphrase, 
the passphrase of any profile can be changed. You should consider if passphrase 
changing should be permitted and, if so, which role(s) should have this authority. 


If any user reports an inability to log on, this should be reported to someone other 
than (or certainly in addition to) an individual with passphrase-changing 
permission. Consider defining roles so that dual-control is required for every 
security sensitive operation to protect against a malicious insider acting on his/her 
own. For example, consider splitting the following groups of access control points 
between two or more roles. It is recommended that one person should not be able 
to use all of the commands in the Master key group, because this could represent a 
security risk. 


The Master key group consists of these access control points: 
* Load 1st part of Master Key 

* Combine Master Key Parts 

* Set Master Key 

* Generate Random Master Key 

* Clear New Master Key Register 

* Clear Old Master Key Register 


By the same token, one person should not be authorized to all of the commands in 
the Cloning key group. 


The Cloning key group consists of these access control points: 
* Initialize Master Key Cloning Control 

* Register Public Key Hash 

* Register Public Key, with Cloning 

* Register Public Key 

* PKA Clone Key Generate 
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¢ Clone-Information Obtain Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
* Clone-Information Install Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 


After you create and define a profile for your 4758 Coprocessor, you_must load_a 
function control vector for your 4758 Coprocessor as described in 


control vector” on page 74} Without the function control vector, your 4758 
Coprocessor cannot perform any cryptographic functions. 


Example: ILE C program for creating roles and profiles for your 
4758 Coprocessor 

Change this program example to suit your needs for creating a role or a profile for 
your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


1 en a ee ee eet «/ 
/* CRTROLEPRF */ 
/* x/ 
/* Sample program to create roles and profiles in the 4758 x/ 
/* cryptographic adapter. x/ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CRTROLEPRF) */ 
/* x/ 
/* Use these commands to compile this program on iSeries server: */ 
/* CRTCMOD MODULE(CRTROLEPRF) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CRTROLEPRF) MODULE (CRTROLEPRF) */ 
/* BNDSRVPGM(QCCA/CSUAACI QCCA/CSNBOWH) */ 
/* x/ 
/* Note: Authority to the CSUAACI and CSNBOWH service programs x/ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verbs used are */ 
/* Access Control_Initialization (CSUAACI) and x/ 
/* One_Way Hash (CSNBOWH). */ 
/* x/ 
/* Note: This program assumes the device you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the x/ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x/ 
/* x/ 
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/* Note: Before running this program, the clock in the 4758 must be */ 


/* set using Cryptographic Facility Control (CSUACFC) in order */ 
/* to be able to logon afterwards. x/ 
/* x/ 
| ee ee ee a a eee ee eee eee ee eee */ 


#include "csucincl.h" 


/* header file 


for CCA Cryptographic 


Service Provider for iSeries 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
void main(int argc, char *argv[]) { 
[eeses seeseeseeeesancaaaseeracesee ses e asec as-seaeeeess=>—seSeesees */ 
/* standard return codes */ 
| ee ee ee eee eet «/ 
#define ERROR -1 
#define OK 0 
#define WARNING 4 
Pisses ace saeeeesesateesea see See see seeeeeseesenae ase aqns=a>—eaesesee> */ 
/* Variables used for parameters on CCA APIs */ 
| ee ee ee eee ee eee eee ee eee eee eee «/ 
long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 
long verb_datal_length; 
long verb_data2_length; 
long hash_length; 
long text_length; 
char «text; 
char chaining vector[128] ; 
long chaining _vector_length; 
/#eeeesecshsosasseeeaecseesscsseeseonsoesneseaanseneacsecseserseecese «/ 
/* Definitions for profiles */ 
Roos sees sossesssseasscseesssesscsscseeSsises ssc sesseesessacessssess */ 
typedef struct 
{ 
char version[2]; /* Profile structure version */ 
short length; /* length of structure x/ 
char comment [20] ; /* Description */ 
short checksum; 
char logon_failure_count; 
char reserved; 
char userid[8]; /x Name for this profile */ 
char role[8]; /* Role that profile uses x/ 
short act_year; /* Activation date - year */ 
char act_month; /* Activation date - month x/ 
char act_day; /* Activation date - day */ 
short exp_year; /* Expiration date - year */ 
char exp_month; /* Expiration date - month */ 
char exp_day; /* Expiration date - day */ 
short total_auth_data_length; 
short field_type; 
short auth_data_length_l; 
short mechanism; /* Authentication mechanism */ 
short strength; /* Strength of mechanism x/ 
short mech_exp_year; /* Mechanism expiration - year*/ 
char mech_exp_month; /* Mech. expiration - month = */ 
char mech_exp_day; /* Mechansim expiration - day */ 
char attributes [4]; 
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char auth_data[20]; /* Secret data 
} profile_T; 


typedef struct 


long number; /* Number profiles in struct 
long reserved; 

profile T  profile[3]; 

} aggregate_profile; 


aggregate_profile * verb_datal; /* Aggregate structure for 
/* defining profiles 


Jesseoeecgeeeessessesessea ss ssess sess cesses ss scsaesessass eases fessaeas 
/* Definitions for roles 

[esse be oeeeetees sece neha e see ee sleds ace sae Se See ee eters ese eesoee see 
| ee ee a eee */ 
/* Default role - access control points list - */ 
/* authorized to everything EXCEPT: */ 
/* 0x0018 - Load 1st part of Master Key x/ 
/* @x0019 - Combine Master Key Parts */ 
/*  @xOQO1A - Set Master Key x/ 
/*  @x0020 - Generate Random Master Key x/ 
/* 0x0032 - Clear New Master Key Register */ 
/* 0x0033 - Clear Old Master Key Register */ 
/* 0x0053 - Load 1st part of PKA Master Key x/ 
/* @x0054 - Combine PKA Master Key Parts */ 
/*  0x0057 - Set PKA Master Key */ 
/* 0x0060 - Clear New PKA Master Key Register */ 
/* 0x0061 - Clear Old PKA Master Key Register */ 
/*  @x@110 - Set Clock x/ 
/*  @x0111 - Reinitialize device x/ 
/*  @x0112 - Initialize access control system */ 
/* 0x0113 - Change user profile expiration date */ 
/*  x0114 - Change authentication data (eg. passphrase) */ 
/*  @x0115 - Reset password failure count */ 
/* @x0116 - Read Public Access Control Information */ 
/* 0x0117 - Delete user profile */ 
/*  x0118 - Delete role x/ 
/* @x0119 - Load Function Control Vector */ 
/*  @x011A - Clear Function Control Vector */ 
/*  x011B - Force User Logoff */ 
/* @x0200 - Register PKA Public Key Hash */ 
/* @x0201 - Register PKA Public Key, with cloning */ 
/*  @x0202 - Register PKA Public Key */ 
/*  0x0203 - Delete Retained Key */ 
/* @x0@204 - PKA Clone Key Generate */ 
/*  @x0211 - 0x21F - Clone information - obtain 1-15 */ 
| FeeeSseesehesatseeteeeeraeceseeerse se Secee eee seeseSeeseosecee */ 


/* For access control points 0x01 - 0x127 */ 
char default_bitmap[] = 
{ 0x00, 0x03, OxFO, Ox1D, 0x00, 0x00, 0x00, 0x00, 
0x80, 0x00, 0x00, 0x00, 0x00, Ox00, Ox00, Ox00, 
0x00, OxOA, 0x80, 0x00, 0x88, Ox2F, Ox71, 0x10, 
0x10, 0x04, 0x03, 0x31, 0x80, 0x00, 0x00, 0x00, 
OxFF, Ox7F, 0x40, Ox6B, 0x80}; 


/* For access control points 0x200 - 0x23F */ 
char default2_bitmap[] = 
{ 0x00, 0x00, Ox00, 0x00, Ox00, Ox00, OxE6, OxOF }; 


[Rese eecceececsterssessessssscaseseeseesssesssesosee sess easeues */ 
/* role #1 - authorized to same as default plus also */ 
/* authorized to: x/ 
/* 0x0018 - Load 1st part of Master Key x/ 
/*  @x0020 - Generate Random Master Key x/ 
/* 0x0032 - Clear New Master Key Register */ 
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/* @x0053 - Load 1st part of PKA Master Key x/ 


/* @x0060 - Clear New PKA Master Key Register */ 
/* @x0119 - Load Function Control Vector */ 
/*  @x0201 - Register PKA Public Key, with cloning */ 
/* @x0202 - Register PKA Public Key x/ 
/*  Qx0203 - Delete Retained Key */ 
/* @x0204 - PKA Clone Key Generate */ 
/*  @x0211 - 0x215 - Clone information - obtain 1-5 */ 
/*  @x0221 - 0x225 - Clone information - install 1-5 */ 
| Rees eeeeseees aceasta easecs=esaesee= seecese-ceaeeeeesesa=>—soe-e */ 


char rolel_bitmap[] = 
{ 0x00, 0x03, OxFO, Ox9D, 0x80, Ox00, 0x20, 0x00, 
0x80, 0x00, 0x10, 0x00, Ox80, 0x00, 0x00, 0x00, 
0x00, OxOA, Ox80, 0x00, Ox88, Ox1F, 0x71, 0x10, 
0x10, 0x04, 0x03, 0x11, Ox80, 0x00, 0x00, 0x00, 
OxFF, Ox7F, 0x00, Ox4F, 0x80}; 
char rolel_bitmap2[] = 
{ 0x78, 0x00, Ox7C, 0x00, Ox7C, 0x00, OxE6, OxOF }; 


| ee oe oe ee ee eee ee eee */ 
/* role #2 - authorized to same as default plus also */ 
/* authorized to: x/ 
/* Qx0019 - Combine Master Key Parts x/ 
/*  Qx@O1A - Set Master Key x/ 
/* @x0033 - Clear Old Master Key Register */ 
/* Qx0054 - Combine PKA Master Key Parts x/ 
/*  @x0057 - Set PKA Master Key */ 
/* @x0061 - Clear Old Master Key Register */ 
/*  @x011A - Clear Function Control Vector */ 
/* @x0200 - Register PKA Public Key Hash */ 
/*  @x0201 - Register PKA Public Key, with cloning */ 
/*  0x0203 - Delete Retained Key */ 
/* Qx@204 - PKA Clone Key Generate x*/ 
/*  @x0216 - 0x21A - Clone information - obtain 6-10 */ 
/*  @x0226 - 0x22A - Clone information - install 6-10 */ 
| eee ee ee */ 


char role2_bitmap[] = 
{ 0x00, 0x03, OxFO, Ox7D, 0x80, 0x00, 0x10, 0x00, 
0x80, 0x00, 0x09, 0x00, Ox40, Ox00, 0x00, 0x00, 
0x00, OxOA, Ox80, 0x00, Ox88, Ox1F, 0x71, 0x10, 
0x10, 0x04, 0x03, 0x31, Ox80, 0x00, 0x00, 0x00, 
OxFF, Ox7F, 0x00, Ox2F, 0x80}; 
char role2_bitmap2[] = 
{ OxD8, 0x00, 0x03, OxEO, 0x03, OxEO, OxE6, OxOF }; 


| ee eee */ 
/* role #3 - authorized to same as default plus also */ 
/* authorized to: x/ 
/*  x0110 - Set Clock x/ 
/*  Qx@111 - Reinitialize device x/ 
/*  @x0112 - Initialize access control system */ 
/* @x0113 - Change user profile expiration date */ 
/*  x0114 - Change authentication data (eg. passphrase) */ 
/*  @x0115 - Reset password failure count */ 
/* @x0116 - Read Public Access Control Information */ 
/* @x0117 - Delete user profile */ 
/*  Qx0118 - Delete role x/ 
/*  x011B - Force User Logoff x*/ 
/* @x0200 - Register PKA Public Key Hash */ 
/*  @x0201 - Register PKA Public Key, with cloning */ 
/*  Qx0203 - Delete Retained Key x/ 
/* Qx@204 - PKA Clone Key Generate x/ 
/*  @x021B - 0x21F - Clone information - obtain 11-15 */ 
/*  @x022B - 0x22F - Clone information - install 11-15 */ 
[#eeeseeebiccbeeceaaste asses sseesssseseesaeesasasencsceeesesseses */ 


char role3_bitmap[] = 
{ 0x00, 0x03, OxFO, Ox1D, 0x00, 0x00, 0x00, 0x00, 
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0x80, 0x00, 0x00, 

0x00, OxOA, Ox80, 

0x10, 0x04, 0x03, 

OxFF, Ox7F, OxFF, 

char role3_bitmap2[] = 
{ 0xD8, 0x00, 0x00, 


0x00, OxCO, 0x00, 0x00, 
0x00, 0x88, Ox1F, Ox71, 
0x31, 0x80, 0x00, 0x00, 
Ox9F, 0x80}; 


Ox1F, 0x00, Ox1F, OxE6, 


struct access _control_points_ header 


{ 


short number_segments; 


/* Number of segments of */ 


/* the access points map */ 


short reserved; 
} access_control_points_header; 


struct access _control_points_segment_header 


{ 


short start_bit; /* Starting bit in this */ 
/* segment. x/ 
short end_bit; /* Ending bit */ 
short number_bytes; /* Number of bytes in */ 
/* this segment x/ 
short reserved; 


} access_control_points segment_header; 


[eeepasmes= ee aes asessassesse sees 2s] sees aos soso Se aaa ase */ 
/* Structure for defining a role x/ 
[seeeseacnsesers seo seese ace necse- esses aes ase See ae so aa eae */ 


struct role_header 


{ 


char version[2]; 

short length; 

char comment [20] ; 

short checksum; 

short reservedl; 

char role[8]; 

short auth_strength; 

short lower_time; 

short upper_time; 

char valid_days_of_week; 

char reserved2; 

} role_header; 
[¥en ee cere sees Sees e eee ese case ae eee le See Se ee cess eee eee ces */ 
/* Structure for defining aggregate roles */ 
[ Reeneeeee meee ae aeesecs sesso nee sas sees =e see eee Se Saaaae> = ae eee= */ 
struct aggregate_role_header 

long number; 

long reserved; 

} aggregate_role_header; 
char * verb_data2; 
char * work_ptr; 
char *bitmapl, *bitmap2; 
int i; /* Loop counter */ 
[esse tecesesessecessessseesscesscoseesecesssssesesussossessenscees */ 
/* >>>>>>>> Start of code <<<<<<<<<<<<<<<<<< */ 
[eeSeessesesessestst ease essoessesasesesscee a seasaeeso ose seeee */ 
| ee ee a er ee ee */ 
/* Allocate storage for the aggregate role structure */ 
[eseessccssceesssoasussessssncsseseeseesssesscesceeess-s=osseueS */ 
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verb_data2 = malloc(sizeof(aggregate_role header) + 
sizeof(role header) * 3 + 
sizeof (access control _points_header) * 3 + 
sizeof(access_control_points_segment_header) 
* 6 + /* 3 roles * 2 segments each */ 
sizeof (default_bitmap) * 3 + 
sizeof (default2 bitmap) * 3); 


work_ptr = verb_data2; /* Set working pointer to 
start of verb data 2 storage */ 


aggregate_role_header.number 


= 3; /* Define/replace 3 roles */ 
aggregate_role_header.reserved = 


0; 
/* Copy header into verb data 
2 storage. x*/ 
memcpy (work_ptr, (void*) &aggregate_role_header, 
sizeof (aggregate role header) ); 


/* Adjust work pointer to point 


after header. x/ 
work_ptr += sizeof (aggregate_role_ header); 
/heeeeeeeeeeneen see cseee senses ane ses eee eee seeesecs=assasessses */ 
/* Fill in the fields of the role definitions. */ 


/* Each role is version 1, has authentication strength of 0,  */ 
/* has valid time from 12:00 Midnight (0) to 23:59 (x173B), */ 


/* is valid every day of the week. (xFE is 7 bits set), */ 
/* has one access control points segment that starts at bit 0 ~*/ 
/* and goes to bit x11F, and has 20 spaces for a comment. */ 
| Ran eteeeweseees naa ceeeasesa ae aee aes Sea cesee seaseseasesses-eseee */ 
role_header.version[0] = 1; 


Q; 
sizeof(role header) + 
sizeof(access control points header) + 
2 * sizeof(access control points segment_header) + 
sizeof (default_bitmap) + sizeof (default2_bitmap); 


role_header.version[1] 
role_header. length 


role_header.checksum = 0; 
role_header.reserved1 = 0; 
role_header.auth_strength = 0; 
role_header. lower_time = 0; 
role_header.upper_time = 0x173B; 
role_header.valid_days_of_week = QOxFE; 
role_header.reserved2 = 0; 


memset (role_header.comment,' ', 20); 


access_control_points_header.number_segments = 2; 
access _control_points_header.reserved = 0; 
access_control_points_segment_header.reserved = 0; 
for (i=0; i<3; i++) 
{ 
switch (i) { 
/eeeeeSeesseesees=ess=ss5s seca se ae s2e——5622=455= */ 
/* Set name for ROLE1 */ 
[xesesseseecesessasco sete eee ee eese */ 
case 0: 
memcpy(role_header.role, "ROLE1 ", 8); 
bitmapl = rolel_bitmap; 
bitmap2 = rolel_bitmap2; 
break; 
[xeseseSn sere sose nes cese ee soosssee Sere se see ee esse */ 
/* Set name for ROLE2 */ 
| ee a ee a */ 
case 1: 


memcpy(role_header.role, "ROLE2 ", 8); 
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bitmapl = role2_bitmap; 


bitmap2 = role2_bitmap2; 
break; 
ff ttace eee ae are ae tee aaa ee Ses a eae eae */ 
/* Set name for ROLE3 x/ 
| #esesesesosaaesnassose coeds aeeshesc seen seese ae es */ 
case 2: 


memcpy(role_header.role, "ROLE3 ", 8); 
bitmapl = role3_bitmap; 
bitmap2 = role3_bitmap2; 


} 
Jeeeseeseassacsss sense csassesasesssssssssssseeessSeeu «/ 
/* Copy role header */ 
[heSossceseseceensece see ea seo eons esses essen eeseeee «/ 


memcpy (work_ptr, (void*)&role_header, sizeof(role_header)); 


/* Adjust work pointer to 
point after role header. */ 
work_ptr += sizeof(role_ header); 


jeteeeesseesesssosenseesedsecsecn=cs=-s-sS=5o=ssesac6 «/ 
/* Copy access control points header */ 
| $aeeeseaceaatscs oes sees teeceaeraesaesseoaacseseces] «/ 


memcpy (work_ptr, 
(void *)&access_control_points_ header, 
sizeof (access control _points_header)); 


/* Adjust work pointer to 
point after header. ~*/ 
work_ptr += sizeof(access_control_points_header) ; 


[dese GussessscssescesesseseessssesessSescasseecssseee «/ 
/* Copy access control points segment 1 */ 
[eestosesecesessteeeeresese= seca ese de aces e Seee ese seu «/ 
access_control_points_segment_header.start_bit = 0; 

access _control_points_segment_header.end_bit = 0x127; 


access _control_points_segment_header.number_bytes = 
sizeof (default_bitmap) ; 
memcpy (work_ptr, 
(void *)&access control_points_segment_header, 
sizeof (access _control_points_segment_header)) ; 


/* Adjust work pointer to 
point after header. +*/ 
work_ptr += sizeof(access_control_points_segment_header) ; 


{hesecceeeSeeaseseeseessan=socoseensssssecessesessee= «/ 
/* Copy access control points segment 1 bitmap */ 
[hoseseeceseseeeeeeE ese Hsecee ee see ee see eee eeeeeee «/ 


memcpy(work_ptr, bitmapl, sizeof(default_bitmap)); 


/*x Adjust work pointer to 
point after bitmap. */ 
work_ptr += sizeof (default_bitmap) ; 


[eesoesseeheceesosassecsecseceecnaes=esses—55-55-5456 «/ 
/* Copy access control points segment 2 */ 
[Ros ecseassesesteeeacesedeaeasaqessascssestseusee casos «/ 
access _control_points_segment_header.start_bit = 0x200; 
access _control_points_segment_header.end_bit = Ox23F; 


access _control_points_segment_header.number_bytes = 
sizeof (default2_bitmap) ; 


memcpy (work_ptr, 
(void *)&access control_points_segment_header, 
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sizeof (access _control_points_segment_header)); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access control_points_segment_header) ; 


De ee */ 
/* Copy access control points segment 2 bitmap */ 
peaseasesacssesscssouasssascssesccsesseascsseussseees */ 


memcpy(work_ptr, bitmap2, sizeof (default2_bitmap)); 
/* Adjust work pointer to 


point after bitmap. */ 
work_ptr += sizeof (default2_bitmap); 


verb_datal = malloc(sizeof(aggregate_profile)); 


verb_datal->number 3; /* Define 3 profiles 
verb_datal->reserved = 0; 


/* Each profile: 

/* will be version 1, 

/* have an activation date of 1/1/00, 

/* have an expiration date of 6/30/2005, 


/* use passphrase hashed with SHA1 for the mechanism (0x0001), 


/* will be renewable (attributes = 0x8000) 
/* and has 20 spaces for a comment 


for (i=0; i<3; i++) 
{ 
verb_datal->profile[i].length 
verb_datal->profile[i].version[0] 
verb_datal->profile[i].version[1] 
verb_datal->profile[i] «checksum 
verb_datal->profile[i].logon_failure_count 
verb_datal->profile[i].reserved 
verb_datal->profile[i].act_year = 2000; 


verb_datal->profile[i].act_month = 1; 
verb_datal->profile[i].act_day = 1; 
verb_datal->profile[i].exp_year = 2005; 
verb_datal->profile[i].exp_month B63 
verb_datal->profile[i] .exp_day = 30; 
verb_datal->profile[i].total_auth_data_length = 0x24; 


verb_datal->profile[i].field_type = Qx0001; 


verb_datal->profile[i].auth_data_length_1 = 0x20; 
verb_datal->profile[i] .mechanism = 0x0001; 
verb_datal->profile[i].strength = 0; 
verb_datal->profile[i].mech_exp_year = 2005; 
verb_datal->profile[i] .mech_exp_month = 6; 
verb_datal->profile[i].mech exp day = 30; 


verb_datal->profile[i] .attributes [0] = 0x80; 


verb_datal->profile[i].attributes[1] = Q; 
verb_datal->profile[i].attributes [2] = Q; 
verb_datal->profile[i].attributes [3] = 0; 
memset (verb_datal->profile[i].comment, ' ', 20); 


memcpy(rule_array, "SHA-1 ", 8); 


rule_array_count = 1; 
chaining _vector_length = 128; 
hash_length = 20; 
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switch (i) { 


[eeeebesesotenseossosesoaaeesesseeseeececeeee */ 

/* Set name, role, passphrase of profile 1 */ 

[Reese header aces seses ee esa eeresaes aes ecessee= */ 
case 0: 


memcpy(verb_datal->profile[i].userid,"SECOFR1 ",8); 
memcpy(verb_datal->profile[i].role, "ROLE1 ",8); 
text_length = 10; 


text = "Is it safe"; 
break; 
| eee eee */ 
/* Set name, role, passphrase of profile 2. */ 
[Rossesessessesssssssessesessescsscescessesss */ 
case 1: 


memcpy(verb_datal->profile[i].userid,"SECOFR2 ",8); 
memcpy(verb_datal->profile[i].role, "ROLE2 ",8); 
text_length = 18; 

text = "I think it is safe"; 


break; 
Recs oteeseteneseesests eases eee se sees eee se */ 
/* Set name, role, passphrase of profile 3 */ 
/ eeeoaas see seesessessess=sse es asseaeseoseeeae */ 
case 2: 


memcpy (verb_datal->profile[i] .userid,"SECOFR3 ",8); 
memcpy(verb_datal->profile[i].role, "ROLE3 ",8); 


text_length = 12; 

text = "Is what safe"; 
} 
| ee eee eee ee a */ 
/* Call One _Way_Hash to hash the pass-phrase */ 
| Moe eee mes see aeeseseass ode asacsarsacs=so=—Se5se55 */ 


CSNBOWH( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char*)rule_array, 
&text_length, 
text, 
&chaining_vector_length, 
chaining_vector, 
&hash_length, 
verb_datal->profile[i].auth_data); 


[ eSemenoeares seeseacaesese sase dee es aes sas ensa-eseaseases */ 
/* Call Access Control_Initialize (CSUAACI) to create +*/ 
/* the roles and profiles. */ 
[#eeeeSeeiSseesnsSeseeteee se ose lee esse se eee Seen oeseeee= */ 


rule_array_count = 2; 

memcpy(rule_array, “INIT-AC REPLACE ", 16); 

verb_datal_length = sizeof(aggregate_ profile); 

verb_data2_length = sizeof(aggregate role header) + 
sizeof(role header) * 3 + 
sizeof (access _control_points_header) * 3 + 
sizeof(access_control_points_segment_header) 
«6 + /* 3 roles * 2 segments each */ 
sizeof (default_bitmap) * 3 + 
sizeof (default2 bitmap) * 3; 


CSUAACI( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 


38 iSeries: Cryptographic hardware 


(char *)rule_array, 

(long *) &verb_datal_length, 
(char *) verb _datal, 

(long *) &verb_data2_length, 
(char *) verb_data2); 


if (return_code > WARNING) 
printf("Access Control_Initialize failed. Return/reason codes: \ 
%d/%d\n", return_code, reason_code); 
else 
printf("The new roles and profiles were successfully created\n"); 


/* The Access_Control_Initialize SAPI verb needs to be */ 
/* called one more time to replace the DEFAULT role so that */ 
/* a user that does not log on is not able to change any */ 


/* settings in the 4758. */ 
| $seeeeahsceessesecessses secs secee see eee nsaeseseeeeeseesae= */ 
work_ptr = verb_data2; /* Set working pointer to 


start of verb data 2 storage */ 


aggregate_role header.number = 1; /* Define/replace 1 roles */ 
aggregate_role header.reserved = 0; 
memcpy (work_ptr, (void*) &aggregate_role_header, 

sizeof (aggregate _role header) ); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof (aggregate_role_ header) ; 


/* Fill in the fields of the role definitions. */ 
/* Each role is version 1, has authentication strength of 0, */ 
/* has valid time from 12:00 Midnight (0) to 23:59 (x173B), */ 


/* is valid every day of the week. (xFE is 7 bits set), */ 
/* has one access control points segment that starts at bit 0 */ 
/* and goes to bit x11F, and has 20 spaces for a comment. */ 
| Reeeeeaeaeeaaa sees seeeaaer =ee sees eo saceese=aaees=es==ss55-—-——5 */ 


role_header.version[0] 
role_header.version[1] 
role_header. length = sizeof(role_header) + 
sizeof(access control points header) + 
2 * sizeof(access control points segment_header) + 
sizeof (default_bitmap) + sizeof (default2_bitmap); 

role_header. checksum = 0; 
role_header.reserved1 
role_header.auth_strength 
role_header.lower_time 
role_header.upper_time 
role_header.valid_days_of_week = 
role_header.reserved2 = 
memset (role_header.comment,' ', 20); 


ore 
we we 


access _control_points_header.number_segments = 2; 
access | “control _points_header.reserved = 0; 
access _control_points segment_header. reserved = 0; 


/* DEFAULT role id must be in */ 
/* ASCII representation. x/ 
memcpy(role_header.role, "\x44\x45\x46\x41\x55\x4C\x54\x20", 8); 
bitmapl = default_bitmap; 
bitmap2 = default2_bitmap; 


/ #eeceeseseeeSeesassseesesessSeeecsesseeseeessesaeeaso */ 
/* Copy role header x/ 
| ReesaaeSearees= cS aceneeacsaseacesssseesceceseoseses= */ 


memcpy (work_ptr, (void*)&role_header, sizeof(role_header)); 
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/* Adjust work pointer to 
point after header. +*/ 
work_ptr += sizeof(role_ header) ; 


| ee ee ee ee ee eee oe eee oe */ 
/* Copy access control points header */ 
| ose cocesseessesesseeeeeesse ease ese seekeeeoseeesesee */ 


memcpy (work_ptr, 
(void *)&access_control_points header, 
sizeof(access control _points_header)); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access_control_points_ header) ; 


| ee ee eee ee */ 
/* Copy access control points segment 1 */ 
/ Rtaceeoussssssssesseesescassesscuesessst ssosceocsess */ 
access_control_points_segment_header.start_bit = 0; 

access_control_points_segment_header.end_bit = 0x127; 


access_control_points_segment_header.number_bytes = 
sizeof (default_bitmap) ; 
memcpy (work_ptr, 
(void *)&access control_points_segment_header, 
sizeof(access_control_points_segment_header) ); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access control_points_segment_header) ; 


| ee eee eet */ 
/* Copy access control points segment 1 bitmap */ 
/ Reece ecuessesssses ceceeesessassesescesescsescesesssS */ 


memcpy(work_ptr, bitmapl, sizeof (default_bitmap)); 


/*x Adjust work pointer to 
point after bitmap. */ 
work_ptr += sizeof (default_bitmap) ; 


[#eSeee cee esses esse eee esse ese Se os esses ee Sees */ 
/* Copy access control points segment 2 */ 
[#Seceraes=eeses Se seessese re ecs=asseeaeseses—S=oees */ 
access_control_points_segment_header.start_bit = 0x200; 
access_control_points_segment_header.end_bit = 0x23F; 


access_control_points_segment_header.number_bytes = 
sizeof (default2_bitmap) ; 


memcpy (work_ptr, 
(void *)&access control_points_segment_header, 
sizeof(access_control_points_segment_header) ); 


/*x Adjust work pointer to 
point after header. ~*/ 
work_ptr += sizeof(access_control_points_segment_header) ; 


[eesetsecsesesscsesseeseesessesseseesceseseesessuseos */ 
/* Copy access control points segment 2 bitmap */ 
[Roce eeeee cesses st seenseessseaeeeesehessceSseeeeeseese */ 


memcpy(work_ptr, bitmap2, sizeof (default2_bitmap)); 


rule_array_count = 2; 

memcpy(rule_array, “INIT-AC REPLACE ", 16); 

verb_datal_length = 0; 

verb_data2_length = sizeof(aggregate_role header) + 
sizeof(role_ header) + 
sizeof(access control points header) + 
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sizeof (access control _points_segment_header) 
x2 + 

sizeof(default_bitmap) + 

sizeof (default2_bitmap) ; 


CSUAACI( &return_code, 


&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 

(char *)rule_array, 

(long *) &verb_datal_length, 
(char *) verb _datal, 

(long *) &verb_data2_length, 
(char *) verb_data2); 


if (return_code > 4) 
printf("The default role was not replaced. Return/reason code: \ 


else 


%d/%d\n",return_code, reason_code); 


printf("The default role was successfully updated. \n"); 


} 


Example: ILE RPG program for creating roles or profiles for your 
4758 Coprocessor 
Change this program example to suit your needs for creating roles and profiles for 
your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DAK RAKKAKKKK KEK KK KEK KKK ERK KKK KKK KERR KR RRR KR RRR RRR ERK RR ERR RRR 


Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx 
Dx 
Dx 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 


CRTROLEPRF 


Sample program to create 3 roles and 3 profiles in the 4758 
and change the authority for the default role. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these programs. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: None 


Example: 
CALL PGM(CRTROLEPRF) 


Use these commands to compile this program on iSeries: 

CRTRPGMOD MODULE(CRTROLEPRF) SRCFILE(SAMPLE) 

CRTPGM PGM(CRTROLEPRF) MODULE (CRTROLEPRF) 
BNDDIR(QCCA/QC6BNDDIR) 


Note: Authority to the CSUAACI service program in the 
QCCA library is assumed. 
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Dx« 
D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Access Control_Initialize (CSUAACI) 


Dx« 

DA RRA KKKKKKK KER KEK KKK KKK KR KK KEKE KKK RRR KKK RRR KER KERR RR KK RRR KERR 
PeseesesSessocscesecasessccsosssseSs Sess ssseossossssscescs 
D* Declare variables used by CCA SAPI calls 

Pesceseee seca eee See ses eee eeeeeee See eee eee ee eee esse 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITDATALEN S 9B 0 

D« xx Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Text length 

DTEXTLEN S 9B 0 

Dx ** Text to hash 

DTEXT S 20 

D* ** Chaining vector length 

DCHAINVCTLEN S 9B @ INZ(128) 

Dx ** Chaining vector 

DCHAINVCT S 128 

D* ** Hash length 

DHASHLEN S 9B 0 INZ(20) 

DeeSeseed stee esse ewes See eee ee eee See eee eee eee See eee ee 
D* VERBDATA1 contains the aggregate profile structure which 
D* in turn contains 3 profiles. 
D¥eseeSscoslcseseeccasececss cesses s secs seseeosslasceecesSeesssS 
DVERBDATALEN1 S 9B @ INZ(278) 

DVERBDATA1 DS 278 

Dx ** Define 3 Profiles 

DNUMPROFS 9B 0 INZ(3) 

Dx ** Reserved field 

DRESR1 9B 0 INZ(0) 

DPROF1 90 

DPROF2 90 

DPROF3 90 

Dx« 

[DE ee a ee et 
Dx Define the profile structure 
Deeseeeecsseecsocstes sc ssolceoesoosesess essa soeSossssecesossesse 
DPROFILESTRUCT DS 

Dx ** Version 1 struct 

DPROFVERS 2 INZ(X'0100') 

D* ** Length of profile 

DPROFLEN 2 INZ(X'Q05A') 

D« ** Description of profile 

DCOMMENTP 20 INZ(' 

Dx ** Checksum is not used 

DCHECKSUMP 2 INZ(X'Q000') 

D* ** Logon failure count 

DLOGFC 1 INZ(X'00') 

Dx ** Reserved 

DRESR2 1 INZ(X'00') 

Dx ** Profile name 

DUSERID 8 

Dx ** Role used 

DROLENAME 8 

Dx ** Activation year (2000) 

DACTYEAR 2 INZ(X'07D0') 

Dx *x* Activation month (01) 
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DACTMONTH 1 INZ(X'01') 


Dx xx Activation day (01) 

DACTDAY 1 INZ(X'01') 
Dx xx Expiration year (2004) 
DEXPYEAR 2 INZ(X'07D4') 
Dx *x* Expiration month (12) 
DEXPMONTH 1 INZ(X'OC') 
Dx **x Expiration day (31) 

DEXPDAY 1 INZ(X'1F') 
D« ** Total authentication 

Dx ** data length 

DTOTAUTDTALEN 2 INZ(X'0024') 
Dx ** Field type 

DFIELDTYPE 2 INZ(X'Q001') 
D« ** Authentication data len 
DAUTDATLEN 2 INZ(X'0020') 
Dx ** Authentication mechanism 
DMECHANISM 2 INZ(X'0001') 
D* ** Mechanism strength 

DSTRENGTH 2 INZ(X'Q000') 
Dx ** Mech expiration year (2004) 
DMCHEXPYEAR 2 INZ(X'07D4') 
Dx *x* Mech expiration month (12) 
DMCHEXPMONTH 1 INZ(X'OC') 
Dx *x* Mech expiration day (31) 
DMCHEXPDAY 1 INZ(X'1F') 
Dx ** Attributes 

DATTRIBUTES 4 INZ(X'80000000' ) 
D* «x Authentication data 
DAUTHDATA 20 INZ(' Y) 
Dx 

Dkee ese esrece ce clesl else see eet ose eee eee ee See eee See ese ec 


D* The Default role is being replaced 
D* Verb_data_2 length set to the length of the default role 


D* VERBDATA2 contains the aggregate role structure which 
D* in turn contains 3 roles. 


DeSe eee ease eeeesee sates ee ee eee eee eee eee eee se eee ete eS 
DVERBDATA2 DS 

Dx ** Define 3 Roles 

DNUMROLES 9B © INZ(3) 

D« «x Reserved field 

DRESR3 9B 0 INZ(O) 

DROLE1 109 

DROLE2 109 

DROLE3 109 

Dx 

Peet teeeere et Sea ee sche n esse bee Se eee oe eee 
D* Define the role structure 
DPxeeeeteecescsecsecssccseSeecleceoseSseesSssesseseosscesecsSesseee 
DROLESTRUCT DS 

D« ** Version 1 struct 

DROLEVERS 2 INZ(X'0100') 

D« ** Length of role 

DROLELEN Z INZ(X'QO6D') 

Dx ** Description of role 

DCOMMENTR 20 INZ(' ") 
Dx ** Checksum is not used 

DCHECKSUMR 2 INZ(X'Q000 ') 

D* «x Reserved field 

DRESR4 2 INZ(X'0000') 

Dx «x Role Name 

DROLE 8 

Dx xx Authentication strength is set to 0 
DAUTHSTRN Zz INZ(X'Q000') 
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Dx «x Lower time is 00:00 


DLWRTIMHR 1 INZ(X'00') 

DLWRTIMMN 1 INZ(X'00') 

Dx ** Upper time is 23:59 

DUPRTIMHR 1 INZ(X'17') 

DUPRTIMMN 1 INZ(X'3B') 

Dx ** Valid days of week 

DVALIDDOW 1 INZ(X'FE') 

D« ** Reserved field 

DRESR5 1 INZ(X'00') 

Dx ** 2 Access control points segments are defined 
DNUMSEG 2 INZ(X'0002') 

D* ** Reserved field 

DRESR6 2 INZ(X'Q000') 

Dx ** Starting bit of segment 1 is 0 

DSTART1 2 INZ(X'0000') 

Dx xx Ending bit of segment 1 is 295 (Hex 127). 
DEND1 2 INZ(X'0127') 

Dx ** 37 Bytes in segment 1 

DNUMBYTES1 2 INZ(X'0025') 

D* ** Reserved field 

DRESR7 2 INZ(X'00') 

D« ** Segment 1 access control pointer 
DBITMAP1A 8 

DBITMAP1B 8 

DBITMAP1C 8 

DBITMAP1D 8 

DBITMAP1E 5 

D* ** Starting bit of segment 2 is 512 (Hex 200) 
DSTART2 2 INZ(X'0200') 

Dx xx Ending bit of segment 2 is 575 (Hex 23F) 
DEND2 2 INZ(X'023F') 

D« xx 8 Bytes in segment 2 

DNUMBYTES2 2 INZ(X'Q008') 

D* ** Reserved field 

DRESR8 2 INZ(X'0000') 

Dx ** Segment 2 access control points 
DBITMAP2 8 

Dx« 

Dx« (ese e oes eae eee eee esau * 

D* * DEFAULT expressed in ASCII * 

Dx« fSeSSsscessseeesoesssssssosesee * 

DDEFAULT Ss 8 INZ(X'44454641554C5420') 
Dx« 

DA KRRKKKKKKK KEK KKK KEK KK KERR RRR KERR KERR RK RRR ER RRR ERK RERERER 
D* Prototype for Access Control Initialize (CSUAACI) 

DA RRA KKKKKKK KER KKK KEK KKK KR KKK KR KKK KR RK KERR KKK KER RRR ERK KERR 
DCSUAACI PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN1 9B 0 

DVRBDTA1 278 

DVRBDTALEN2 9B 0 

DVRBDTA2 335 

Dx« 

DA RRR KKK KKK KK ERK KEKE KKK KERR KERR KERR KERR ER KERR KER KER E RRR ER KER RERERREEE 
D* Prototype for One _Way_Hash (CSNBOWH) 

DARK RKKKKKK KK ERK KK EK KKK ERK KKK KK KK KR KEK KERR KKK RE RR KR RRR RERERE 


DCSNBOWH PR 

DRETCOD 9B 0 
DRSNCOD 9B 0 
DEXTDTALN 9B 0 
DEXTDT 4 
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DRARRYCT 9B 0 


Cx 
Cx« 


0x0203 - Delete Retained Key 
0x0204 - PKA Clone Key Generate 


DRARRY 16 
DTXTLEN 9B 0 
DTXT 20 
DCHNVCTLEN 9B 0 
DCHNVCT 128 
DHSHLEN 9B 0 
DHSH 20 
Dx« 
DkeeSaSaeeSas 5S - ape Sea ese oes eae ae oe Se eae See Sea eee eae Se SSeS == 
Dx ** Declares for sending messages to the 
Dx ** job log using the QMHSNDPM API 
Deeseece cose cecoee See ese ees eee eee eee cee eee see see eee 
DMSG S 64 DIM(3) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(64) 
D DS 
DMSGTEXT 1 75 
DSAPI 1 7 
DFAILRETC 41 44 
DFAILRSNC 46 49 
DMESSAGEID S 7‘ INZ(' ') 
DMESSAGEFILE > 21 INZ(' ') 
DMSGKEY S 4 INZ(! ') 
DMSGTYPE S 10 INZ('*INFO *) 
DSTACKENTRY S 10 INZ('* ") 
DSTACKCOUNTER Ss 9B 0 INZ(2) 
DERRCODE DS 
DBYTESIN 1 4B 0 INZ(Q) 
DBYTESOUT 5 8B 0 INZ(0) 
Cx« 
CR KKK KK KKK KKK KEKE KR EKER KER ERK KK RK EKER KEKE RR ER ERR RR EKER KERR ERR ERE 
Cx START OF PROGRAM * 
Cx« * 
GxeseesecsecesscsccecScessossesecseese cs eSs ces eseeseSst esc oseee * 
Cx Set up roles in verb data 2 * 
CxeseeaeteeeoseSseee et Sse eee Sece noes see Se ste ee ce Se eee ees * 
Cx Set ROLE name (ROLE1) 
C MOVEL "ROLE1 : ROLE 
Gx “WeeecectsstcscoeseessessosccscesceseSsesscsesssssescesce 
Cx »* Set Access Control Points for ROLE1 
Cx * 
Cx »* DEFAULT is authorized to all access control points 
Cx »* except for the following: 
Cx x 0x0018 - Load 1st part of Master Key 
Cx * 0x0019 - Combine Master Key Parts 
Cx * Ox001A - Set Master Key 
Cx * 0x0020 - Generate Random Master Key 
Cx x 0x0032 - Clear New Master Key Register 
Cx * 0x0033 - Clear Old Master Key Register 
Cx * Ox00D6 - Translate CV 
Cx * 0x0110 - Set Clock 
Cx x Ox@111 - Reinitialize device 
Cx * 0x0112 - Initialize access control system 
Cx * 0x0113 - Change user profile expiration date 
Cx * 0x0114 - Change authentication data (eg. passphrase) 
Cx * 0x@115 - Reset password failure count 
Cx x 0x@116 - Read Public Access Control Information 
Cx x 0x@117 - Delete user profile 
Cx * 0x0118 - Delete role 
Cx * 0x0119 - Load Function Control Vector 
Cx * Ox@11A - Clear Function Control Vector 
Cx x 0x@11B - Force User Logoff 
Cx * 0x0200 - Register PKA Public Key Hash 
Cx * 0x0201 - Register PKA Public Key, with cloning 
Cx * 0x0202 - Register PKA Public Key 
* 
* 
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Cx* 
Cx 
C* 
C* 
C* 
Cx* 
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+ * FF F FF F F F HF F F FF F F F HF F 


+ 


+ 


+ + F F 


0x0211 - Ox21F - Clone information - obtain 1-15 
0x0221 - Ox22F - Clone information - install 1-15 


ROLE 1 is authorized to all access control points 
to which the DEFAULT role is authorized plus the following: 


0x0018 
0x0020 
0x0032 
0x0053 
0x0060 
0x0119 
0x0201 
0x0202 
0x0203 
0x0204 
0x0211 
0x0221 


Load 1st part of Master Key 

Generate Random Master Key 

Clear New Master Key Register 

Load 1st part of PKA Master Key 

Clear New PKA Master Key Register 

Load Function Control Vector 

Register PKA Public Key, with cloning 
Register PKA Public Key 

Delete Retained Key 

PKA Clone Key Generate 

0x215 - Clone information - obtain 1-5 
0x225 - Clone information - install 1-5 


EVAL BITMAP1A = X'0003F09D80002000 ' 
EVAL BITMAP1B = X'8000100080000000 ' 
EVAL BITMAPIC = X'000A8000881F7110' 
EVAL BITMAP1D = X'1004031180000000' 
EVAL BITMAP1LE = X'FF7FOQO4F80' 

EVAL BITMAP2 = X'78007COO7COOE6OF ' 


Copy role into aggregate structure 


MOVEL ROLESTRUCT ROLE1 


Set ROLE name (ROLEZ2) 


MOVEL "ROLE2 =! ROLE 


Set Access Control Points for ROLE2 


ROLE 2 is authorized to all access control points 
to which the DEFAULT role is authorized plus the following: 


0x0019 
Ox001A 
0x0033 
0x0054 
0x0057 
0x0061 
OxO011A 
0x0200 
0x0201 


Combine Master Key Parts 

Set Master Key 

Clear Old Master Key Register 

Combine PKA Master Key Parts 

Set PKA Master Key 

Clear Old Master Key Register 

Clear Function Control Vector 

Register PKA Public Key Hash 

Register PKA Public Key, with cloning 
Delete Retained Key 

PKA Clone Key Generate 

Ox21A - Clone information - obtain 6-10 
0x22A - Clone information - install 6-10 


EVAL BITMAP1A = X'0003F07D80001000' 
EVAL BITMAP1B = X'8000090040000000' 
EVAL BITMAPIC = X'Q00A8000881F7110' 
EVAL BITMAP1D = X'1004031180000000' 
EVAL BITMAPLE = X'FF7FOQO2F80' 

EVAL BITMAP2 = X'D80003EQ03EOE60F ' 


Copy role into aggregate structure 


MOVEL ROLESTRUCT ROLE2 


Set ROLE name (ROLE3) 


MOVEL "ROLE3 ROLE 


Set Access Control Points for ROLE3 


ROLE 3 is authorized to all access control points 
to which the DEFAULT role is authorized plus the following: 


Cx* 


Cx 


+ + + 


+ 


+ + + 


+ 


* 


AAR DWOAIAaAAIQDODOOaDWOAaAAaAAOaAAMBDO:000 08:0 


0x0110 
0x@111 
0x0112 
0x0113 
0x0114 
0x0115 
0x0116 
0x0117 
0x0118 
0x011B 
0x0200 
0x0201 
0x0203 
0x0204 
0x021B 
0x022B 


+ + FF FF F F F F HF HF F F F HF 


Set Clock 

Reinitialize device 

Initialize access control system 

Change user profile expiration date 
Change authentication data (eg. passphrase) 
Reset password failure count 

Read Public Access Control Information 
Delete user profile 

Delete role 

Force User Logoff 

Register PKA Public Key Hash 

Register PKA Public Key, with cloning 
Delete Retained Key 

PKA Clone Key Generate 

Ox21F - Clone information - obtain 11-15 
Ox22F - Clone information - instal] 11-15 


EVAL BITMAPIA = X'0003F01D00000000' 
EVAL BITMAP1B = X'80000000C0000000' 
EVAL BITMAPIC = X'Q00A8000881F7110' 
EVAL BITMAP1D = X'1004021180000000' 
EVAL BITMAPIE = X'FF7FFF9F80' 

EVAL BITMAP2 = X'D800001FOO1FE60F ' 


Copy role into aggregate structure 


MOVEL ROLESTRUCT ROLE3 


Set Profile name (SECOFR1) 


Set Role name (ROLE1) 


MOVEL "SECOFRI ' USERID 
MOVEL "ROLE1 : ROLENAME 
Hash pass-phrase for profile 1 
SETOFF 05 
EVAL TEXT = 'Is it safe' 
Z-ADD 10 TEXTLEN 
EXSR HASHMSG 
SETON LR 


05 


Copy profile into aggregate structure 


MOVEL PROFILESTRUCT PROF1 


Set Profile name (SECOFR2) 


Set Role name (ROLEZ) 


MOVEL "SECOFR2 ' USERID 
MOVEL "ROLE2 ROLENAME 
Hash pass-phrase for profile 2 
EVAL TEXT = 'I think it is safe' 
Z-ADD 18 TEXTLEN 
EXSR HASHMSG 
SETON LR 


05 


Copy profile into aggregate structure 


MOVEL PROFILESTRUCT PROF2 


Set Profile name (SECOFR3) 


Set Role name (ROLE3) 


MOVEL "SECOFR2 ' USERID 
MOVEL "ROLE3 ROLENAME 
Hash pass-phrase for profile 3 
EVAL TEXT = 'Is what safe' 
Z-ADD 12 TEXTLEN 
EXSR HASHMSG 
SETON LR 


05 


Copy profile into aggregate structure 


MOVEL PROFILESTRUCT PROF3 


Ckeseeeseeeseece nce scnecse see eessee se eeeese ace seeseeseeessesxe * 
Cx Set the keywords in the rule array * 
Chae wee ree ee ee ee ee eee ee se i eee eee eee ese * 
C MOVEL 'INIT-AC ' RULEARRAY 
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C MOVE "REPLACE ' RULEARRAY 
C Z-ADD 2 RULEARRAYCNT 


CR KKK KKK KEK KKK KEKE KKK KERR EKER ERK RK ER KERR ERE RR EK ERE RR EK ERE RR EKER 


Cx Call Access _Control_Initialize SAPI 


CR KKK KKK KEK KKK KKK KKK KER KKK ERE KK RK ER KEK KEKE KR EKER KERR EK ERE RK EKER EK 


C CALLP CSUAACT (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 

C RULEARRAY : 

C VERBDATALEN1: 

C VERBDATAI: 

C VERBDATALEN2: 

C VERBDATA2) 

C* sc a ih i a * 

Cx »* Check the return code * 

C* cs i ec * 

C RETURNCODE IFGT 0 

C* macs ceceseseesesesecoces * 

Cx * Send failure message * 

C* fecseaccrascecaaesescones * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSUAACI' SAPI 

C EXSR SNDMSG 

C RETURN 

C ELSE 

C* anc eeeseeawe seeesseese= * 

Cx * Send success message * 

C* Ce ee ee * 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

C ENDIF 

C* 

CkXeeecscesee cence teresa see seo See ses see ese eee seee Soe sceeSso5 * 
Cx Change the Default Role * 
(CW eee eee eee se sen se eee ees ee echoes ese ee sees e eee estes * 
Cx Set the Role name 

C MOVEL DEFAULT ROLE 

CX WSscceciscsccccuesecscltsossocssoosecsesescescaslSscseesess 
Cx * Set Access Control Points for DEFAULT 

Cx «* 

Ck Wesessssese eos ce seeeseeise sss soeeeesesereet esses seseeseee 
C EVAL BITMAPIA = X'0003F01D00000000' 
C EVAL BITMAP1B = X'8000000000000000' 
C EVAL BITMAPIC = X'0Q0A8000881F7110' 
C EVAL BITMAP1D = X'1004021180000000' 
C EVAL BITMAP1E = X'FF7F406B80' 

C EVAL BITMAP2 = X'OQODQDQDQD000E6OF ' 
Cx Copy role into aggregate structure 


C MOVEL ROLESTRUCT ROLE1 

C* 

Cx Set the new verb data 2 length 

C Z-ADD 117 VERBDATALEN2 
Cx* 

Cx Set the verb data 1 length to 0 (No profiles) 

C Z-ADD 0 VERBDATALEN1 
Cx Change the number of roles to 1 

C Z-ADD 1 NUMROLES 

C 


CR KKK KKK EK KKK KEKE KK EKER KERR ERE RK RK EKER KER ERR ER ERE RR EK ERE RK EKER 
C* Call Access Control_Initialize SAPI 

CR KKK KKK KEK KKK KEKE KKK KEKE EK EKER KKK ERK KR EK ERR ER ERE RR EK ERR RR EKER 
C CALLP CSUAACI (RETURNCODE: 

Cc REASONCODE: 
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C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C VERBDATALEN1: 
C VERBDATAI: 

C VERBDATALEN2: 
C VERBDATAZ) 
Ck¥eeesee-e see se sees ns * 

Cx Check the return code * 

Cxeseccscosselstsecesosecs * 

C RETURNCODE IFGT 0 

Cx Pies ane sees eee eee * 

Cx * Send failure message * 

Cx Reite see ee eee seweeeceeeens * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSUAACI' SAPI 

C EXSR SNDMSG 

Cx* 

C ELSE 

Cx« (oscinceescaccasseeesecess * 

Cx * Send success message * 

Cx« tees cass oocesaenasasesees * 

C MOVEL MSG(3) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ENDIF 

Cx« 

C SETON LR 
Cx« 


CK KKK KKK KKK KKK KERR KEKE KK KK ERK KK EKER KERR EK ERR EKER KERR ERE REE ERR ERE 


Cx Subroutine to send a message 
CRRA KKK KEK KK KEKE KR EKER KER ERK KK RK EKER KEK ERR ER ERR RRR ERE RR ERR ERE 


C SNDMSG BEGSR 


C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


CK KK KK KKK KKK KEKE KR EKER KER ERK KK RK ERE RK EKER ER ERE REKRE REE ERRERE 
Cx Subroutine to Hash pass-phrase 
CR KKK KKK KEK KKK KKK KR EKER KER ERE RK RK EKER KEK ERR EKER KERR EKER KERR ERR 


C HASHMSG BEGSR 


Cx« Jeceseesecscaeseaseeseseceooeeoeess<eeseecs * 

Cx »* Set the keywords in the rule array * 

Cx* {csmsccatnona sso sa SaaS eae ec aaeccassaSceoaeeeS * 

C MOVEL "SHA-1 RULEARRAY 

C Z-ADD i; RULEARRAYCNT 
Cx« Jecksesscosaaecessaceseese * 

Cx »* Call One Way Hash SAPI * 

Cx* {csccetaececacace seo me eee Ss * 

C CALLP CSNBOWH (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT : 
C RULEARRAY : 

C TEXTLEN: 


Chapter 4. 4758 Cryptographic Coprocessor for iSeries 


49 


C TEXT: 

C CHAINVCTLEN: 
C CHAINVCT: 
C HASHLEN: 
C AUTHDATA) 
Cx #eSecccSscesseosssesscsse * 

Cx * Check the return code * 

(Ck Resee cheese See cesses ece * 

C RETURNCODE IFGT 0 

Cx* ¥ssssssesaosssesessesaese * 

Cx * Send failure message * 

C* Pescoeessssessseteeeeeese * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C MOVEL "CSNBOWH' SAPI 

C EXSR SNDMSG 

C SETON 05 
C ENDIF 

Cx* 

C ENDSR 


K* 

CSUAACI failed with return/reason codes 9999/9999. 

SECOFR1, SECOFR2, and SECOFR3 profiles were successfully created. 
The Default role was successfully changed. 


Example: ILE C program for enabling all access control points in 
the default role for your 4758 Coprocessor 

Change this program example to suit your needs for enabling all access control 
points in the default role for your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


(Ps teeeee tases aeeere oe esce se cesses eaaneea es SSeS ose es ese eases —essosas */ 
/* SETDEFAULT */ 
/* x/ 
/* Sample program to authorize the default role to all access x/ 
/* control points in the 4758. x/ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: */ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(SETDEFAULT) */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* CRTCMOD MODULE(SETDEFAULT) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(SETDEFAULT) MODULE (SETDEFAULT) */ 
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/* BNDSRVPGM(QCCA/CSUAACT) 


/* 

/* Note: Authority to the CSUAACI service programs 
/* in the QCCA library is assumed. 

/* 


/* The Common Cryptographic Architecture (CCA) verb used is 
/* Access Control_Initialization (CSUAACI). 


/* 

/* Note: This program assumes the device you want to use is 

/* already identified either by defaulting to the CRPO1 

/* device or has been explicitly named using the 

/* Cryptographic_Resource Allocate verb. Also this 

/* device must be varied on and you must be authorized 

/* to use this device description. 

/* 

[Reseeseaee sees eet see ees beet ee eee eet See epee ee cee Ses eeetencs 
#include "csucincl.h" /* header file for CCA Cryptographic 


Service Provider for iSeries 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


void main(int argc, char *argv[]) { 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


long return_code; 

long reason_code; 

long exit_data_length; 
char exit_data[2]; 

char rule_array[4] [8]; 
long rule_array_count; 
long verb_datal_length; 
long verb_data2_length; 
char  verb_datal[4]; 


[Reese sneenseqsancemenses=seseese sesso sess —esaessee=S5-sSe55 */ 
/* Structure for defining a role x/ 
[Hoses seasicas sone see see ceas anes e ses enese eerie aes nesceeeseestae= */ 
struct role_header 

{ 

char version[2]; 

short length; 

char comment [20] ; 

short checksum; 

short reserved1; 

char role[8]; 

short auth_strength; 

char lower_time_hour; 

char lower_time_minute; 

char upper_time_hour; 

char upper_time_minute; 

char valid_days_of_week; 

char reserved2; 


} role_header; 
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Ss 


Ss 


Ss 


/* 
/* 
/* 
/* 


ch 


ch 


Hesse eteeets es seceuese see scesocesosscsecceececceeueetseeeecues */ 
* Structure for defining aggregate roles */ 
a ee a ee ee ee ee */ 
truct aggregate_role 

long number; 

long reserved; 


} aggregate_role_header; 


ee ee ee ee ee ee eee */ 
* Structures for defining the access control points in a role */ 
ee a a a ae ae a ae */ 
truct access_control_points_ header 

{ 

short number_segments ; /* Number of segments of */ 

/* the access points map */ 
short reserved; 


} access_control_points_header; 


truct access _control_points_segment_header 
{ 

short start_bit; /* Starting bit in this */ 
/* segment. x/ 

short end_bit; /* Ending bit */ 

short number_bytes; /* Number of bytes in */ 
/* this segment x/ 

short reserved; 


} access_control_points_segment_header; 


Default role - access control points list - 
authorized to everything 


For access control points @xQ1 - 0x127 
ar default_bitmap[] = 
{ 0x00, 0x03, OxFO, OxFD, 0x80, 0x00, 0x30, 0x00, 
0x80, Ox00, 0x19, 0x00, OxCO, 0x00, 0x00, 0x00, 
0x00, OxOA, 0x80, Ox00, Ox88, Ox2F, 0x71, 0x10, 
0x18, 0x04, 0x03, 0x31, 0x80, 0x00, 0x00, 0x00, 
OxFF, Ox7F, OxFF, OxFF, 0x80}; 


ar default2_bitmap[] = 
{ O@xF8, 0x00, Ox7F, OxFF, Ox7F, OxFF, OxE6, OxOF }; 


unsigned char * verb_data2; 

unsigned char * work_ptr; 

int i; /* Loop counter */ 
| ee ee a eee eee */ 
/* Start of code */ 
[eesoeneasscossssesscessssscsssssessessee ses sceecsssssesseaseees */ 
| Freese escenses seseeeseesece se acese ses seeesseeesees peas scesese */ 
/* Allocate storage for the aggregate role structure x/ 
[eee= Saas sacs ass dee see seeoe ners aaeseeeaes cases eserese=so-saens= */ 


verb_data2 = malloc(sizeof(aggregate_role header) + 


sizeof(role_ header) + 
sizeof(access_control_points_header) + 
sizeof(access_control_points_segment_header) 
x2 + 

sizeof(default_bitmap) + 
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sizeof (default2_bitmap)); 
work_ptr = verb_data2; /* Set up work pointer */ 


aggregate_role_header.number 


= 1;  /* Define/replace 1 role */ 
aggregate_role_header.reserved = 


0; /* Initialize reserved field*/ 


/* Copy header to verb_data2 
storage. x/ 
memcpy (work_ptr, (void*) &aggregate_role_header, 
sizeof (aggregate_role header) ); 


work_ptr += sizeof(aggregate_role header); /* Set work pointer 
after role header */ 


[Resa oleesSeesee Sees shee se leases eeteeeetee ee eee dee cee sess */ 
/* Fill in the fields of the role definition. */ 
[#secaeshsesseseses eeee oon sense tse sseesenesesereeaeSscessessese */ 
role header.version[0] = 1; /* Version 1 role */ 
role_header.version[1] = 0; 
/* Set length of the role */ 

role _header.length =  sizeof(role header) 

+ sizeof(access_control_points_header) 

+2* 


sizeof(access_control_points_segment_header) 
+ sizeof (default_bitmap) 
+ sizeof (default2_ bitmap); 


role_header.checksum = 0; /* Checksum is not used */ 

role_header.reserved1 = 03 /* Reserved must be 0 */ 

role_header.auth_strength = 0; /* Authentication strength */ 
/* is set to 0. */ 
/* Lower time is 00:00 */ 

role_header.1]ower_time_hour = 0; 

role_header.lower_time_minute = 0; 
/* Upper time is 23:59 */ 

role_header.upper_time_hour 2233 

role_header.upper_time_minute = 59; 

role_header.valid_days_of_week = OxFE; /* Valid every day */ 
/* 7 bits - 1 bit each day */ 

role_header.reserved2 = 0; /* Reserved must be 0 */ 
/* Role is DEFAULT */ 
/* expressed in ASCII x/ 


memcpy(role_header.role, "\x44\x45\x46\x41\x55\x4C\x54\x20", 8); 


memset (role_header.comment,' ',20); /* No description for role */ 


/Reesseselssoss-seese cesses sesso sseseesesssesecssesee */ 
/* Copy role header into verb_data2 storage x/ 
| eee seseesesecesocehce See ese saeceeeseemeeeensee ss */ 


memcpy (work_ptr, (void*)&role_ header, sizeof(role_header)) ; 
work_ptr += sizeof(role_ header) ; 


/ Raeeseeeasseaease=seeesues=ssaseseeseseeeoss2-esees= */ 
/* Set up access control points header and then */ 
/* copy it into verb_data2 storage. */ 
| Raeeaseeeesece= o55caeeaseeaasacesesseeseeoese-eesea= */ 


access_control_points_header.number_segments 
access _control_points_header.reserved 
access _control_points_segment_header.reserved = 


memcpy (work_ptr, 
(void *)&access_control_points_header, 
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sizeof(access_control_points_header) ); 


/* Adjust work_ptr to point to the 
first segment x*/ 
work_ptr += sizeof(access_control_points_header) ; 


[xSb assess sseaaseasseenanesssesesasessasseseeseeecesS */ 
/* Set up the segment header for segment 1 and then */ 
/* copy into verb_data2 storage */ 
{eeeeeeaasecs aqs aes sees eece=sesasesaeones ae aaoeeeees */ 
access_control_points_segment_header.start_bit = 0; 

access_control_points_segment_header.end_bit = 0x127; 


access_control_points_segment_header.number_bytes = 
sizeof (default_bitmap) ; 
memcpy (work_ptr, 
(void *)&access_control_points_segment_header, 
sizeof(access control_points_segment_header)); 


/* Adjust work_ptr to point to the 
first segment bitmap */ 
work_ptr += sizeof(access_control_points_segment_header) ; 


ReaeaseeeScesaseaosereeesessesasesses=esece=cSssasa— */ 
/* Copy access control points segment 1 bitmap */ 
[eeeateaesaasssseee seeeeeseasecaoeeaceaes Heese eaeeas */ 


memcpy(work_ptr, default_bitmap, sizeof (default_bitmap)); 


/* Adjust work_ptr to point to the 
second segment */ 
work_ptr += sizeof (default_bitmap) ; 


| ee eet te eet */ 
/* Set up the segment header for segment 2 and then */ 
/* copy into verb_data2 storage x/ 
[Hesense sasaensseeeceasesascene enn saseaseeer een eeasss */ 


access_control_points_segment_header.start_bit = 0x200; 
access_control_points_segment_header.end_bit 
access_control_points_segment_header.number_bytes = 

sizeof (default2_bitmap) ; 


I 
oO 
x< 
ine) 
w 
7 

v 


memcpy (work_ptr, 
(void *)&access_control_points_segment_header, 
sizeof(access_control_points_segment_header) ); 


/* Adjust work_ptr to point to the 
second segment bitmap x/ 
work_ptr += sizeof(access_control_points_segment_header) ; 


| FoSaseecsesssas sess eeteessseseccess sss seeceeseceese */ 
/* Copy access control points segment 2 bitmap */ 
[Reeneseeeedeese ses teee ee as— see ee eee seeseee See eoesS */ 
memcpy(work_ptr, default2_bitmap, sizeof (default2_bitmap)); 
| Hoon Sees eeessssereeesee esse ase cesssesseeeceeaeassse */ 
/* Set the length of verb data 2 (Role definition) */ 
[see as eeasass eas ae sees eee asc r eae s=eSees oseseeeseee= */ 


verb_data2_length = sizeof(aggregate_role header) + 
role_header. length; 


| a ae eee ee eee */ 
/* Set remaining parameters x/ 
[essemsccsesessssesseesesecesessesresesssscessssoseos */ 


rule_array_count = 2; 
memcpy(rule_array, "“INIT-AC REPLACE ", 16); 
verb_datal_length = 0; 
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/* Call Access Control_Initialize (CSUAACI) to set the */ 
/* default role. */ 


CSUAACI( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char *)rule_array, 
&averb_datal_length, 
(unsigned char *) verb_datal, 
&verb_data2_length, 
verb_data2) ; 


if (return_code > 4) 

printf("The default role was not replaced. Return/reason code: \ 
%d/%d\n",return_code, reason_code); 

else 

printf("The default role was successfully updated. \n"); 


} 


Example: ILE RPG program for enabling all access control points 


in the default role for your 4758 Coprocessor 


Change this program example to suit your needs for enabling all access control 


points in the default role for your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DARK RK KARR KK KEK KKK KKK KEKE RK KKK KKK KKK KEK KERR KK RRR KERR ERK RR ERRRRREK 
D* SETDEFAULT 

Dx 

D* Sample program to authorize the default role to all access 
D* control points in the 4758. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx 

D* Example: 

D* CALL PGM(SETDEFAULT) 

Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(SETDEFAULT) SRCFILE(SAMPLE) 
D* CRTPGM PGM(SETEID) MODULE (SETDEFAULT) 


D« BNDSRVPGM(QCCA/CSUAACT) 

Dx 

D* Note: Authority to the CSUAACI service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
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D* Access Control_Initialize (CSUAACI) 


Dx« 

DA KRAK KKK KKK KEKE KKK KKK KERR KERR KEK KERR REE RRR RRR RRR KERR RRR RRR KERR 
DxeeSeee eee se Se cece eee eee ee ee sees Ss See een sees eco et eee 
D* Declare variables used by CCA SAPI calls 
DkecesccccscosscesoetscsscseceseseeSesceaseocaseaelSsesiecs 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx xx Exit data length 

DEXITDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D« ** Verb data 1 length 

DVERBDATALEN1 S 9B 0 INZ(0) 

Dx ** Verb data 1 

DVERBDATA1 S 4 

D« ** Verb data 2 length 

DVERBDATALEN2 S 9B @ INZ(117) 

DeeSS eS SceS see Soest Sao ae SS ae See aa = Sa eee ae = a == 


D* Verbdata 2 contains the aggregate role structure which 
D* in turn contains 1 role - the default role 


Deer SeeeSesssseasaea sesso a see ese sen ease se seaa seas ass==—es—=sSese5 
DVERBDATA2 DS 200 

Dx ** Define 1 Role 

DNUMROLES 9B © INZ(1) 

Dx ** Reserved field 

DRESR1 9B 0 INZ(0) 

Dx ** Version 1 struct 

DVERS 2 INZ(X'0100') 

Dx ** Length of role 

DROLELEN 2 INZ(X'006D') 

D* ** Description of role 

DCOMMENT 20 INZ(' ‘) 
Dx ** Checksum is not used 

DCHECKSUM 2 INZ(X'0000') 

Dx *x Reserved field 

DRESR2 2 INZ(X'Q000') 

D* ** Role Name is DEFAULT expressed in ASCII 
DROLE 8 INZ(X'44454641554C5420') 
D* ** Authentication strength is set to 0 
DAUTHSTRN 2 INZ(X'Q000') 

Dx ** Lower time is 00:00 

DLWRTIMHR 1 INZ(X'00') 

DLWRTIMMN 1 INZ(X'00') 

Dx ** Upper time is 23:59 

DUPRTIMHR 1 INZ(X'17') 

DUPRTIMMN 1 INZ(X'3B') 

Dx ** Valid days of week 

DVALIDDOW 1 INZ(X'FE') 

Dx ** Reserved field 

DRESR3 1 INZ(X'00') 

Dx *x 2 Access control points segements are defined 
DNUMSEG 2 INZ(X'0002') 

Dx ** Reserved field 

DRESR4 2 INZ(X'Q000') 

Dx ** Starting bit of segment 1 is 0. 

DSTART1 2 INZ(X'0000') 

Dx *x Ending bit of segment 1 is 295 (Hex 127). 
DEND1 2 INZ(X'Q127') 

Dx *x 37 Bytes in segment 1 

DNUMBYTES1 2 INZ(X'0025') 
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D* «x Reserved field 


DRESR5 2 INZ(X'00') 

Dx ** Segment 1 access control points 
DBITMAP1A 8 INZ(X'0003FOFD80003000' ) 
DBITMAP1B 8 INZ(X'80001900C0000000' ) 
DBITMAP1C 8 INZ(X'Q00A8000882F7110') 
DBITMAP1D 8 INZ(X'1804033180000000' ) 
DBITMAP1E 5 INZ(X'FF7FFFFF80' ) 

Dx xx Starting bit of segment 2 is 512 (Hex 200). 
DSTART2 2 INZ(X'0200') 

Dx x* Ending bit of segment 2 is 575 (Hex 23F) 
DEND2 2 INZ(X'023F') 

Dx ** 8 Bytes in segment 2 

DNUMBYTES2 Z INZ(X'0008') 

Dx xx Reserved field 

DRESR6 2 INZ(X'0000') 

Dx ** Segment 2 access control points 

DBITMAP2 8 INZ(X'F8007FFF7FFFE60F ' ) 
Dx 


DA KRRKKKKK KK KEK KKK KKK KK ERK KKK KKK KK RRR KKK KK KEKE RRR RKE KKK ERE 


D* Prototype for Access Control Initialize (CSUAACI) 


DA KRKKKKKKK KK ERK KKK KKK KERR KER KERR KERR RRR RRR KER ERR ER KERR EERE 


DCSUAACI PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN1 9B 0 

DVRBDTA1L 4 

DVRBDTALEN2 9B 0 

DVRBDTA2 200 

Dx« 

Dkeeeee ee sans eaaees ee eaeeee hese eeeec eee ee ee eee eee eats ee 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
DeeSSiSseeaos--=-SSse aa Sas ease e esos asa = Soa eae SSeS a= sea ese 
DMSG S 64 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(64) 

D DS 

DMSGTEXT 1 64 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' F) 
DMSGKEY Ss 4 INZ(' | 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B © INZ(Q) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 

CR KKK KKK KKK KK KKK KK EKER KER ERK KK EKER KER KEK ERR EKER ERR EKER ERR ERR 
Cx START OF PROGRAM * 
Cx * 
CexeSSiesossessosesssosse lessee ee sssee sae ae saa seeeoss——ss—s = * 
Cx Set the keywords in the rule array * 
Cteesstseeeneseeccskesesesensensesecowen Sebo aeceeoesee ened * 
C MOVEL "INIT-AC ! RULEARRAY 

C MOVE "REPLACE ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 


CR KKK KKK KEK KKK KKK KR EKER KER ERK K RK EKER KEK ERR EKER KERR ERE RE RK EERERE 


C* Call Access _Control_Initialize SAPI 


CR KKK KKK KKK KKK KEK RRR ERK EK ERK KK EKER KEK KEK KERR ERE RK RR EKER KER ERR ERE 


C CALLP CSUAACI (RETURNCODE: 
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** 


CO O-ul 'C) a 


Ckeeeeee eee ese nte see ene * 

Cx Check the return code * 

se ee * 

C RETURNCODE IFGT 4 

Cx keSssescescososssesessecse * 

Cx * Send failure message * 

C* I at oo en wa * 

C MOVEL MSG(1) 

C MOVE RETURNCODE 
C MOVE REASONCODE 
C EXSR SNDMSG 
C* 

C ELSE 

Cx koeosesoeeassseoesesse= * 
Cx * Send success message * 
Cx KoaSeeasesss=—=seseeoeo * 
C MOVE MSG (2) 

C EXSR SNDMSG 
Cx 

C ENDIF 

Cx* 

C SETON 

C* 


REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
VERBDATALEN1: 
VERBDATA1: 
VERBDATALENZ2: 
VERBDATAZ2) 


MSGTEXT 
FAILRETC 
FAILRSNC 


MSGTEXT 


LR 


CR KKK KKK EK KKK KKK KKK KEK KKK ERE KK KEK ERE KK KEKE KR EK ERE RR EK ERE RR ERE REE 


Cx Subroutine to send a message 


CR KKK KKK KEK KKK KKK KKK KEKE ER ERE RK RK EKER KER ERR ER ERE RR EK ERE RR EKER 


SNDMSG BEGSR 
CALL 
PARM 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PARM 
ENDSR 


i 


VOUS AVM OO OS Ai 


"QMHSNDPM ' 


MESSAGEID 
MESSAGEFILE 
MSGTEXT 
MSGLENGTH 
MSGTYPE 
STACKENTRY 
STACKCOUNTER 
MSGKEY 
ERRCODE 


CSUAACI failed with return/reason codes 9999/9999. 


Th 


e Default role was successfully set. 


Example: ILE C program for changing an existing profile for your 
4758 Coprocessor 
Change this program example to suit your needs for changing an existing profile 
for your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


/* 
/* 
/* 
/* 
/* 
/* 
/* 


important legal information. 


ee eee ee ee ee ee */ 
Change certain fields in a user profile on the 4758 x/ 
card. This program changes the expiration date using a new */ 
date in the form YYYYMMDD. */ 
x/ 

x/ 

COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 

* 

/ 


iSeries: Cryptographic hardware 


/* This material contains programming source code for your x/ 


/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. */ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: */ 
/* none. x/ 
/* x/ 
/* Example: */ 
/* — CALL PGM(CHG_PROF) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Access Control_Initialization (CSUAACI). */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(CHG_PROF) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CHG_PROF) MODULE (CHG_PROF) x/ 
/* BNDSRVPGM(QCCA/CSUAACI) x/ 
/* x/ 
/* Note: Authority to the CSUAACI service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Access Control_Initialization (CSUAACI). x/ 
/* x/ 
[Stasesetassessechessesesnsscese esse eessreseaesseneaceeeseseosee sess «/ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries */ 


#include <stdio.h> 

#include <string.h> 
#include <stdlib.h> 
#include <decimal.h> 


/#eseesesassaesese esse tesnsaceseeSeeasasen eee e ss sen eaceaeseseeseesese */ 
/* standard return codes */ 
[RosesdessosaessssenseoessssssseccesseeSsisesssses senses sesoseseessesS */ 


#define ERROR -l 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 
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/* standard CCA parameters */ 


iT) 
oO 


long return_code 
long reason "code = 0; 

long exit data _length = 2; 
char exit_data[4]; 

char rule_array[8]; 

long rule_array_count = 1; 


| eee Soest ssesseeessetessaeSceseseresees seas sosesastS=— seen SSoeeecses */ 
/* fields unique to this sample program */ 
| er eae eee */ 


long verb_data_length; 
char * verb_data; 
long verb_data_length2; 
char * verb_data2; 


memcpy (rule_array, "CHGEXPDT",8) ; /* set rule array keywords */ 
verb_data_length = 8; 
verb_data = "SECOFR1 "; /* set the profile name */ 
verb_data_length2 = 8; 
verb_data2 = "20010621"; /* set the new date x/ 
/* invoke verb to change the expiration date in specified profile x/ 


CSUAACI( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data, 
&verb_data_length2, 
verb_data2) ; 


f ( (return_code == OK) | (return_code == WARNING) ) 

{ 
printf("Profile expiration date was changed successfully"); 
printf(" with return/reason codes "); 

printf ("%ld/%ld\n\n", return_code, reason_code); 
return(0K); 

} 


else 
{ 
printf("Change of expiration date failed with return/"); 
printf("reason codes "); 
printf(" %1d/%ld\n\n", return_code, reason_code); 
return (ERROR) ; 
} 


Example: ILE RPG program for changing an existing profile for 
your 4758 Coprocessor 

Change this program example to suit your needs for changing an existing profile 
for your 4758 Coprocessor. 
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Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


Dx« 
Dx« 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx 
Dx« 


Dx« 
DR 
Dx 
DR 
Dx« 
DE 
Dx 
DE 
Dx 
DR 
Dx« 
DR 
Dx 
DV 


KKKKKKKK KKK KEKE KEKE KK KERR KEK KR KKK KKK KKK KKK KKK KKK KKEKKERKKERKRERKEEEE 


CHG_PROF 


Change certain fields in a user profile on the 4758 
card. This program changes the expiration date using a new 
date in the form YYYYMMDD. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these programs. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: Profile 


Example: 
CALL PGM(CHG_PROF) PARM(PROFILE) 


Use these commands to compile this program on iSeries: 

CRTRPGMOD MODULE(CHG_PROF) SRCFILE (SAMPLE) 

CRTPGM PGM(CHG_PROF) MODULE(CHG PROF) 
BNDDIR(QCCA/QC6BNDDIR) 


Note: Authority to the CSUAACI service program in the 
QCCA library is assumed. 


The Common Cryptographic Architecture (CCA) verbs used are 
Access Control_Initialize (CSUAACI) 


This program assumes the card with the profile is 
already identified either by defaulting to the CRPO1 
device or by being explicitly named using the 
Cryptographic_Resource_ Allocate verb. Also this 
device must be varied on and you must be authorized 


to use this device description. 

KEK KKK KK KKK KEK KEKE KKK KKK EKER KEKE KEE KER ERR ERK KERR REE KEKE KER RRKEKEEKERKEER 
Declare variables for CCA SAPI calls 

** Return code 
ETURNCODE Ss 9B 0 

** Reason code 
EASONCODE S 9B 0 

** Exit data length 
XITDATALEN S 9B 0 

xx Exit data 
XITDATA S 4 

** Rule array count 
ULEARRAYCNT S 9B 0 

** Rule array 
ULEARRAY Ss 16 

** Verb data 1 length 
ERBDATALEN1 S 9B 0 INZ(8) 
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D« «x Verb data 1 


DVERBDATA1 S 8 

D* ** Verb data 2 length 
DVERBDATALEN2 S 9B © INZ(8) 
D* ** Verb data 2 
DVERBDATA2 S 8 

Dx« 

Dx« 


DARK A KKK KKK KK ER KKK KEK KKK KKK KKK KEK KKK RRR KKK KEK KERR RRR ERK KERR 


D* Prototype for Access Control_Initialize (CSUAACI) 


DARK RKKKKKKK KERR KK EK KKK KKK KKK KEK KKK RRR KERR KKK KERR KK ER KK RERERREKEK 


DCSUAACI PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN1 9B 0 

DVRBDTA1 8 

DVRBDTALEN2 9B 0 

DVRBDTA2 8 

Dx« 

ee ee eee ee ee 
Dx *x Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Peeessceeee cesses ee soso sea se Se sel Soe ee sense esol See ese ace ee See 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 4l 44 

DFATLRSNC 46 49 

DMESSAGEID 5 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' ry 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* Hy 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

CR KKK KKK KEK KKK EKER RK KEK KKK ERE KKK KEK KEK KKK ERR ER ERE RR EK ERE RR EKER E 
Cx START OF PROGRAM * 
C* * 
CkXteetece eke aeeee tee Sates eo eee ee eee See cette ee eee cee * 
Cx Parameter is profile to be changed. * 
(CeeeSeesaesoeseasesseosesoasa aa seeeS as oaS=—4-5465255-=-5—-—=-——— * 
C *ENTRY PLIST 

C PARM VERBDATA1 

Cteeseese eee esese ese neseee eee sees e eee eseeeeHe sesso eee eeese * 
Cx Set the keywords in the rule array * 
Ck eee eee ees eee see eee we eee eee eee see cesses sees * 
C MOVEL "CHGEXPDT ' RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 
eee ee ee eee eee * 
Cx Set new expiration date * 
(CxeaeaoSsseeceosessosssacessaaSaesa—s=—>sse4s=S55es—2—Ss—=555—5 * 
C MOVEL '20061231' VERBDATA2 
CXseSaseeeesessasises senses eees ose ae eee ewe seeee eee seseessees * 
Cx Call Access Control_Initialize SAPI * 
Oe eee eee ee * 
C CALLP CSUAACI (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 
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C RULEARRAY : 

C VERBDATALEN1: 
C VERBDATA1: 

C VERBDATALEN2: 
C VERBDATA2) 
C¥essseeee see ann eee eee es * 

Cx Check the return code * 

(*----------------------- * 

C RETURNCODE IFGT 0 

Cx« tacaceasaaaseaecceseess * 

Cx * Send error message * 

Cx* (aoccceca cma aaa cee om eS * 

C MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx* 

C ELSE 

Cx* Ssacaacuncecasaaaceeeaee * 

Cx * Send success message * 

Cx Peeecce eee seesseeseeeee * 

C MOVE MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ENDIF 

Cx* 

C SETON LR 
Cx« 


CR KKK KKK KKK KK EKER RK KEK KEK ERK KK EKER KEK KEK KERR ERE RRR ERE KKK ERR ERE 


Cx Subroutine to send a message 
CR KKK KK KKK KKK KEKE KR EKER KER ERK KK RK EKER KEKE RR EKER KERR ERE REE ERR 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


** 


CSUAACI failed with return/reason codes 9999/9999' 
The request completed successfully 


Set the environment ID and clock 
The Environment ID (EID) 


Your 4758 Coprocessor stores the EID as an identifier. The easiest and fastest way 
to set the EID is to use the 4758 Cryptographic Coprocessor configuration 
web-based utility found off of the iSeries Tasks page at http: //server-name:2001. 
The utility includes the Basic configuration wizard that is used when the 
Coprocessor is in an uninitialized state. If the 4758 Coprocessor already has been 
initialized, then click on Manage configuration and then click on Attributes to set 
the EID. 


If you would prefer to write your own application to set the EID, you can do so by 
using the Cryptographic_Facility_Control (CSUACFC) API verb. Two example 
programs are provided for your consideration. One of them is written in ILE C, 
while the other is written in ILE RPG. Both perform the same function. 
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* |“Example: ILE C program for setting the environment ID on your 4758 


* |“Example: ILE RPG program for setting the environment ID on your 4758 
Coprocessor” on page 66 


Your 4758 Coprocessor copies the EID into every PKA key token that your 4758 
Coprocessor creates. The EID helps the 4758 Coprocessor identify keys that it 
created as opposed to keys that another 4758 Coprocessor created. 


The Clock 


The 4758 Coprocessor uses its clock-calendar to record time and date and to 
determine whether a profile can log on. The default time is Greenwich Mean Time 
(GMT). Because of its function, you should set the clock inside your 4758 
Coprocessor before removing the default role’s capability of setting it. 


The easiest and fastest way to set the clock is to use the 4758 Cryptographic 
Coprocessor configuration web-based utility found off of the iSeries Tasks page at 
http://server-name:2001. The utility includes the Basic configuration wizard that is 
used when the Coprocessor is in an uninitialized state. If the 4758 Coprocessor 
already has been initialized, then use click on Manage configuration and then 
click on Attributes to set the clock. 


If you would prefer to write your own application to set the clock, you can do so 
by using the Cryptographic_Facility_Control (CSUACFC) API verb. Two example 
programs are provided for your consideration. One of them is written in ILE C, 
while the other is written in ILE RPG. Both perform the same function. 


¢ |“Example: ILE C program for setting the clock on your 4758 Coprocessor” on 


Example: ILE C program for setting the environment ID on your 
4758 Coprocessor 

Change this program example to suit your needs for setting the environment ID on 
your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


[RecSesSeetese ser eese she eeas =p see de ese eee eee ee eeeee se see eos «/ 
/* Set the environment ID on the 4758 card, based on a */ 
/* 16-byte sample value defined in this program. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 

/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 


iSeries: Cryptographic hardware 


/* IBM 4758 CCA Basic Services Reference and Guide */ 

/* (SC31-8609) publication. */ 

/* */ 

/* Parameters: */ 

/* none. */ 

/* x/ 

/* Example: */ 

/* CALL PGM(SETEID) */ 

/* x/ 

/* x/ 

/* Note: This program assumes the device to use is x/ 

/* already identified either by defaulting to the CRPO1 x/ 

/* device or by being explicitly named using the */ 

/* Cryptographic Resource Allocate verb. Also this */ 

/* device must be varied on and you must be authorized */ 

/* to use this device description. */ 

/* x/ 

/* Use these commands to compile this program on iSeries: x/ 

/* ADDLIBLE LIB(QCCA) x/ 

/* CRTCMOD MODULE(SETEID) SRCFILE(SAMPLE) */ 

/* CRTPGM PGM(SETEID) MODULE(SETEID) */ 

/* BNDSRVPGM(QCCA/CSUACFC) */ 

/* x/ 

/* Note: Authority to the CSUACFC service program in the x/ 

/* QCCA library is assumed. */ 

/* x/ 

/* The Common Cryptographic Architecture (CCA) verb used is x/ 

/* Cryptographic_Facilites Control (CSUACFC). x/ 

/* x/ 

[Remo wae easeees ena sas sseee aes accesses Sessa aee eae s—=s—aee eee */ 

#include "csucincl.h" /* header file for CCA Cryptographic x/ 

/* Service Provider for iSeries */ 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

[Resse asaseesesscescsacunesssessacs ess sasises assess sess as see seen seee ss «/ 

/* standard return codes */ 

[Resse Sese seat eae eee eee seece asap eee ease eee cee see Seeeee cee */ 

#define ERROR -1 

#define OK 0 

#define WARNING 4 

int main(int argc, char *argv[]) 

{ 
JReseeeeesaeee tee o toe soe eee sae ee Stee eee sees ace aces See Sse cee oes «/ 
/* standard CCA parameters x/ 
i) Reces Seen se san aa seem e see =o = Seen ee a5 =e ae a eee ae «/ 
long return_code = 0; 
long reason_code = 0; 
long exit_data_length = 2; 
char exit_data[4]; 
char rule_array[2] [8]; 
long rule_array_count = 2; 
[#sesecsscssetsesecseetssessececsesssces sass sosesaseeseesSseslseesee «/ 
/* fields unique to this sample program */ 
/ #eesecceseses2scesesesss es seeseseteeeece eee eae sere eee «/ 


long verb_data_length; 
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char * verb_data = "SOME ID data 160"; 

/* set keywords in the rule array */ 
memcpy (rule_array,"ADAPTERISET-EID ", 16); 

verb_data_length = 16; 

/* invoke the verb to set the environment ID */ 


CSUACFC (&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data); 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 


printf("Environment ID was successfully set with "); 
printf("return/reason codes %ld/%ld\n\n", return_code, reason_code); 


return(0K) ; 
} 


else 
printf("An error occurred while setting the environment ID.\n"); 
printf("Return/reason codes %ld/%ld\n\n", return_code, reason_code) ; 


return(ERROR) ; 
} 
} 


Example: ILE RPG program for setting the environment ID on 


your 4758 Coprocessor 
Change this program example to suit your needs for setting the environment ID on 
your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


DA KKKKKKKKKK KKK KER KKK ERK KR KER KEKE RR KK REE RRR RRR KER RRR KERKEKRERREREREE 
D* SETEID 

Dx 

D* Set the environment ID on the 4758 card, based on a 

D* 16-byte sample value defined in this program. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 

Dx« 

Dx 
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Dx Note: Input format is more fully described in Chapter 2 of 


D« IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx 

D* Example: 

D* CALL PGM(SETEID) 

Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(SETEID) SRCFILE(SAMPLE) 
D* CRTPGM PGM(SETEID) MODULE(SETEID) 


Dx BNDSRVPGM(QCCA/CSUACFC) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 


Dx 

DA KRAKKKKKKK KER KEK KKK KKK ERK KERR KKK KERR RRR KERR ERR RR ERR KR RERERRRRER 
Dkee esi esaeSceeeces sees sees eee see eee eSpace Se 
D* Declare variables for CCA SAPI calls 
DkeeecescsscsscescesSeesscssssscsosseesessccsssoss 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx xx Exit data length 
DEXITDATALEN Ss 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT Ss 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Verb data length 
DVERBDATALEN S 9B 0 

D* «x Verb data 

DVERBDATA S 16 INZ('Card ID 01234567') 
Dx 

Dx 


DARK RKKKKK KK KER KKK KKK KK ERK KKK KKK KEKE RK RRR KKK KER KEK KERR ER ERREREK 


D* Prototype for Cryptographic_Facilty_Control (CSUACFC) 


DAKAR KKKK KKK KER KKK KERR KEKE RRR RRR K KERR RRR RRR RK ER RRR ERK KER ERRERE 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 16 

Dx« 

DxeeeSeSeasss ses —saSeeo Sse eSee asa Sse sas sas sa aee Sasa = ese osess== 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
Deeeeeeesoecsecceee Se ee eee eee se eee See eee cae eee eee See ee eS 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE Ss 21 INZ(' ') 
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DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ) 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(O) 

C* 

CR KKK KK KK EK KKK KKK KR KK EK KKK ERE KKK ER KKK RK KERR ER ERE RR EK ERE RR EKER 
Cx START OF PROGRAM * 
Cx* * 
CkXeeSescasce ses eseeeeeeese scl Se ise s eee ese ece sees ccscee esos * 
Cx Set the keyword in the rule array * 
CxkSeweSscssesececssessessessccecssece soc eSceccescesossces cu esss * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE 'SET-EID ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 
Ckseeesseesesscesese ese ese ses oleae ese soos ee sees sei ce ees * 
Cx Set the verb data length to 16 * 
(CXeseseSesseeesees sees es acs eaeesoaa ssa - Seo See ease se-ae == Sas * 
C Z-ADD 16 VERBDATALEN 

CR KKK KKK EK KKK KKK KK KK ERK ER EKER KKK ER KEK KEKE RR ER ERE RR EK ERE RR EKER 
Cx Call Cryptographic Facilty Control SAPI x/ 
CR KKK KKK EK KKK KKK KKK KE KKK KEKE RK RK ER KEK KKK KERR ER ERK RRR ERE RRR RRR 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 
CxeessSoSesssoeesease—ssso * 

Cx Check the return code * 

CXaeSeeacuseetesSoeenene = * 

C RETURNCODE IFGT 4 

Cx Hessctnvesvebecesacseees * 

Cx * Send error message * 

Cx hese Gece eee eseeee eee * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx* 

C ELSE 

C* ee ea * 

Cx * Send success message * 

Cx* Se oe ee * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx* 

C ENDIF 

Cx* 

C SETON LR 
(7 


CR KKK KKK KEK KKK KEKE KR KK ERK KK ERE KK RK ER KEK KKK KERR EKER KERR EKER ERK EKER E 


Cx Subroutine to send a message 
CR KKK KK KK EK KKK KKK KKK KEK KKK ERE KKK KEKE KK RK KERR EKER KERR EK ERE RRR RR E 


C SNDMSG BEGSR 

C CALL "QMHSNDPM ' 

¢ PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 

C PARM STACKCOUNTER 


68 iSeries: Cryptographic hardware 


C PARM MSGKEY 
C PARM ERRCODE 
C ENDSR 


** 
CSUACFC failed with return/reason codes 9999/9999. 
The Environment ID was successfully set. 


Example: ILE C program for setting the clock on your 4758 
Coprocessor 

Change this program example to suit your needs for setting the clock on your 4758 
Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


JBewesseesossosasssesecseessecosssossenesessesassseseeescssscsssscess */ 
/* Set the clock on the 4758 card, based on a string from */ 
/* the command line. The command line string must be of */ 
/* form YYYYMMDDHHMMSSWW, where WW is the day of week (01 */ 
/* means Sunday and 07 means Saturday). */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 

/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function x/ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* char * new time 16 characters */ 
/* x/ 
/* Example: */ 
/* CALL PGM(SETCLOCK) PARM('1999021011375204') x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* */ 
/* Use these commands to compile this program on iSeries: x*/ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(SETCLOCK) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(SETCLOCK) MODULE (SETCLOCK) x/ 
/* BNDSRVPGM(QCCA/CSUACFC) x/ 
/* x/ 
/* Note: Authority to the CSUACFC service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Facilities Control (CSUACFC). x/ 
/* x/ 
[easee Sees a eases sles see See ee eee cee Seta ee eee oe ee Soe ese Stee eee «/ 
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#include "csucincl.h" /* header file for CCA Cryptographic x/ 


/* Service Provider for iSeries */ 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
[#eeesesees saeeecesareaeenseceseeese ose sseaSceeseceeseeseseessce=se55 «/ 
/* standard return codes */ 
Wits demiteneaa nesses see e = See oes a= Sea sae ss oa eS eee See ees oeas */ 


#define ERROR -1 

#define OK 0 

#define WARNING 4 

void help(void) 
printf("\n\nThis program loads the time and date into the 4758 card.\n"); 
printf("It requires a single command line parameter containing the \n"); 


printf("new date and time in the form YYYYMMDDHHMMSSWW, where WW is the\n"); 


printf("day of the week, 01 meaning Sunday and 07 meaning Saturday.\n\n"); 


int main(int argc, char *argv[]) 


{ 
(imemeamesnce ace senseeecdsenaqaseossc5=Ss sees Saeseeesoesaeaseosses—=e */ 
/* standard CCA parameters x/ 
[Resesssasessesadet acess Sassen eek eae eesssev ae sesceeese see seesesesees */ 


long return_code 
long reason_code = 0; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 


I 
[<>} 


| Hast eetecssesseses seas ass assesses eeaasoek sees asso sSeaco= ce sescesosee */ 
/* fields unique to this sample program */ 
[¥en Soe ee eee Sse enseeeeeesseeds ose eeeee See Ses eel ett eee */ 


long verb_data_length; 
char * verb_data; 


if (argc != 2) 
help(); 
return(ERROR) ; 
} 
if (strlen(argv[1]) != 16) 
printf("Your input string is not the right length."); 
help(); 
return(ERROR) ; 
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/* set keywords in the rule array */ 
memcpy (rule_array, "ADAPTERISETCLOCK", 16) ; 

verb_data_length = 16; 

/* copy keyboard input for new time x/ 
verb_data = argv[1]; 

/* Set the clock to the time the user gave us x/ 


CSUACFC( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data) ; 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 


printf("Clock was successfully set.\nReturn/"); 
printf("reason codes %1d/%ld\n\n", return_code, reason code); 


return (0K); 
} 


else 


{ 


printf("An error occurred while setting the clock.\nReturn"); 
printf("/reason codes %1d/%ld\n\n", return_code, reason code); 
return (ERROR) ; 

} 


Example: ILE RPG program for setting the clock on your 4758 


Coprocessor 
Change this program example to suit your needs for setting the clock on your 4758 


Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


DAR RRK KAR KKK KEK KKK EK KKK RRR KKK KKK KER KEK KEK KK RRR RR KR ERK RERRRRRRK 
D* SETCLOCK 

Dx« 

D* Set the clock on the 4758 card, based on a string from 

D* the command line. The command line string must be of 

D* form YYYYMMDDHHMMSSWW, where WW is the day of week (01 

D* means Sunday and 07 means Saturday). 

Dx 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 
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D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: 

D« char * new time 16 characters 

Dx« 

Dx Example: 

D* CALL PGM(SETCLOCK) PARM('2000061011375204') 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(SETCLOCK) SRCFILE (SAMPLE) 
D* CRTPGM PGM(SETCLOCK) MODULE(SETCLOCK) 


Dx BNDSRVPGM(QCCA/CSUACFC) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 


Dx« 

DA KRK KKK KKK KK ERK KKK KKK KERR KEKE KKK RRR RE RRR KEKE RRR RRR KEK RR RRRKRRER 
DeeeSeeesseesessaas Sasa aes See ese ea a eae aaa 
D* Declare variables for CCA SAPI calls 
DexeeeeeSeesssas aes eee se SaaS Sa aee See Sa = So ee 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx *x Reason code 

DREASONCODE S 9B 0 

D* ** Exit data length 
DEXITDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Verb data length 
DVERBDATALEN S 9B 0 

D« «x Verb data 

DVERBDATA S 16 

Dx« 

DARK RK KK KKK KK ER KEK KEK K KK KKK KKK KEK KKK RR KK RKE KKK RE RR KR EKR KEK RERRREKEK 


D* Prototype for Cryptographic_Facilty_Control (CSUACFQ) 


DA RRR KARR KK ERK KEKE KKK KERR KERR RRR KERR RR KER KER KR ERE KR RR KK RERREEK 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 16 

Dx« 

DeesSea Sosa sse SaaS eae Sas see Sa aa Sa SS eae = = Se = == 
Dx *x Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Pxeceeeccsceee cece ese cee eee eee eee ee eee eee eee eee eee ece 
DMSG S 75 DIM(6) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 
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DMSGTEXT 1 80 


DFAILRETC 4l 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFTLE S 21 INZ(' 

DMSGKEY Ss 4 INZ(' ny 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER Ss 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 

CXR KKK KEK KKK KKK KKK RK KEK KEK ERK KK EKER KERR EK KERR EKER KERR EKER KERR ERR ERE 
Cx START OF PROGRAM * 
Cx* * 
C *ENTRY PLIST 

C PARM VERBDATA 

Cx« * 
Ckaecseceecas fase assess oS eS Seas See See a aes aaa Saas esse Seeose * 
Cx Check the number of parameters passed in * 
CkeeecSeseetecestessee soo esse cseesee See ees See ses eee eee ss * 
C IF (%PARMS < 1) 

Cx* Hiseslostoeouceus las socssecseseesecseseceec cs eceesecoees * 
Cx * Send message describing the format of the parameter ~* 
Cx* Cees See toate See eee e eS oc e eee See cee eee * 
C MOVEL MSG (3) MSGTEXT 

C EXSR SNDMSG 

C MOVEL MSG(4) MSGTEXT 

C EXSR SNDMSG 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C MOVEL MSG (6) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx« 
CexeSSeeceesessosaoseceseSesae cesses ess ===] 5 s55—-S=>=—55—55= * 
Cx Set the keyword in the rule array * 
CkXee Se ceteeesee ass coke eh eee see ce ease see Reece Sle et ees * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "SETCLOCK' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 
CxSeececcececscsececSeeesSseessssoese cs asf esses ssscosseceeseee * 
Cx Set the verb data length to 16 * 
Cksceeeeseetoscesces ese teee skeet eee * 
C Z-ADD 16 VERBDATALEN 


CRRA KKK KKK KKK KKK RRR EK KKK ERK KK EKER KEK KEK KERR ER ERK RR ERE REE KERR ERE 


Cx Call Cryptographic Facilty Control SAPI 


CR KKK KK KKK KKK KEKE KR KK ERK ER ERK KK RK EKER KEK ERR EKER KERR ERE REE ERR ERE 


€ CALLP CSUACFC (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C VERBDATALEN: 
C VERBDATA) 
Cksseesescecesclecececees * 

Cx Check the return code * 

CxexeSseoseeresessesccescce * 

C RETURNCODE IFGT 4 

Cx« a a eae * 

Cx * Send error message * 

C* a a a ae eee ae * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 
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C MOVE REASONCODE FAILRSNC 


C EXSR SNDMSG 

Cx* 

C ELSE 

Cx kKeeSeeSseesssa=s—eeeeee * 

Cx * Send success message * 

Cx Kees ecce steve see sees * 

C MOVE MSG(2) MSGTEXT 
C EXSR SNDMSG 

Cx* 

C ENDIF 

Cx 

C SETON LR 
C* 


CR KKK KKK EK KKK KEKE KKK KEK KKK ERE KK RK ER KEK KKK KERR ER ERK RRR ERE RR EKER EK 


Cx Subroutine to send a message 
CR KKK KKK EK KKK KEKE KKK KER KER ERE RK EKER KERR EK ERR ER ERE RR EK ERE RR EREERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM ' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 

CSUACFC failed with return/reason codes 9999/9999. 

The request completed successfully. 

This program loads the time and date into the 4758 card. 

It requires a single command line parameter containing the 

new date and time in the form YYYYMMDDHHMMSSWW, where WW is the 
day of the week, 01 meaning Sunday and 07 meaning Saturday. 


Load a function control vector 


After |“Create and define roles and profiles” on page 25} you must load a function 


control vector (FCV) for your 4758 Coprocessor. Without it, your 4758 Coprocessor 
will be unable to perform any cryptographic operations. 


A function control vector is a digitally signed value stored in a file provided by 
IBM. When you install one of the 5722-ACx Cryptographic Access Provider 
products, the file is stored in the root file system with a path of 
/QIBM/ProdData/CAP/FCV.CRT. This value enables the cryptographic 
application within the 4758 Coprocessor to yield a level of cryptographic service 
consistent with applicable import and export regulations. 


The easiest and fastest way to load the FCV is to use the 4758 Cryptographic 
Coprocessor configuration web-based utility found off of the iSeries Tasks page at 
http://server-name:2001. The utility includes the Basic configuration wizard that is 
used when the Coprocessor is in an uninitialized state. If the 4758 Coprocessor 
already has been initialized, then click on Manage configuration and then click on 
Attributes to load the FCV. 


If you would prefer to write your own application to load the FCV, you can do so 
by using the Cryptographic_Facility_Control (CSUACFC) API verb. Two example 
programs are provided for your consideration. One of them is written in ILE C, 
while the other is written in ILE RPG. Both perform the same function. 
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- [Example ILE C program for loading a function control vector for your 4755 
- "Example: ILE RPG program for loading a function control vector for your 4758 


Two other example programs are provided that show how to clear the function 
control vector. One of them is written in ILE C, while the other is written in ILE 
RPG. 


“Example: ILE C program for clearing a function control vector from your 4758 


Coprocessor” on page 82 


“Example: ILE RPG program for clearing a function control vector from your 
4758 Coprocessor” on page 83 


After you load a function control vector for your 4758 Coprocessor, you can load 
and set a master key using|“Load and set a master key” on page 86}to use to 


encrypt keys. 


Example: ILE C program for loading a function control vector for 
your 4758 Coprocessor 

Change this program example to suit your needs for loading a function control 
vector for your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


[Reeebsasessnsoseerisesese soe seese meee e seas sseceeeee ee sake seeee */ 
/* Load the Function Control Vector into the 4758 card. */ 
/* The Function Control Vector enables the cryptographic x*/ 
/* functions of the 4758 card and is shipped with the x/ 
/* Cryptographic Access Provider products. x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 

/* */ 


/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly = */ 


/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function*/ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE ~*/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services forx/ 


/* these programs and files. x/ 
/* x/ 
/* Note: The Function Control Vector is stored in an IFS x/ 
/* file owned by the system. The format of this x/ 
/* vector is described in an appendix of the x/ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* */ 
/* Example: */ 
/* CALL PGM(LOAD_FCV) */ 
/* */ 
/* Note: This program assumes the device you want to load is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the x/ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
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/* Use the following commands to compile this program: */ 


/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(LOAD_FCV) SRCFILE(SAMPLE) SYSIFCOPT(*IFSIO) */ 
/* CRTPGM PGM(LOAD_FCV) MODULE(LOAD_FCV) + x/ 
/* BNDSRVPGM(QCCA/CSUACFC) x/ 
/* x/ 
/* Note: Authority to the CSUACFC service program in the x/ 
/* QCCA library is assumed. x/ 
/* */ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Cryptographic_Facility Control (CSUACFC) x/ 
/* x/ 
[#eseesssassessecsssseeeenSseceseeeane sae sseeeceeseseeseseeeees= */ 


#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

#include <decimal .h> 

#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries 


#pragma linkage(QDCXLATE, OS, nowiden) 
void QDCXLATE(decimal (5,0)*, 

char *, 

char *, 

char *); 


int main(void) 


#define ERROR -1 
#define OK 0 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 


long verb_data_length; 

char *verb_data; 

char buffer[1000]; 

char description[81]; 
decimal(5,0) descr_length = 80; 
int num_bytes; 

FILE *fcv; 


/* retrieve FCV from IBM supplied file 


iSeries: Cryptographic hardware 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 


fcv = fopen("/QIBM/ProdData/CAP/FCV.CRT", "rb"); 
if (fcv==NULL) 


printf("Function Control Vector file not available\n\n"); 
return ERROR; /* File not found or not authorized */ 


} 


num_bytes = fread(buffer,1,1000, fcv) ; 
fclose(fcv); 


if (num_bytes != 802) 


printf("Function Control Vector file has wrong size\n\n"); 


return ERROR; /* Incorrect number of bytes read */ 
} 
[#seeeeesae esa Seaesesesee eo ece see ease sen seca ane see e see seeeceeseee= */ 
/* extract fields in FCV needed by 4758 card */ 
/* Note: use offsets and lengths from CCA publication listed earlier */ 
[#eseeheeessese eset sscses She See eee eae eee eee theca ceescee eee «/ 


memcpy(description, &buffer[390] ,80); 

description[80] = 0; 

QDCXLATE(&descr_length, description, "QEBCDIC ", "QSYS a 
printf("Loading Function Control Vector: %s\n",description) ; 


verb_data_length = 204; 
verb_data = &buffer[470]; 


rule_array_count = 2; 
memcpy ((char*)rule_array, "ADAPTERILOAD-FCV", 16) ; 


[eases ssadessessaescoacupassasessesecseesessestesssessessssocaeseesas «/ 
/* Load the 4758 card with the FCV just retrieved */ 
[eases eee seeds sescee cee eee See ee ee sense eee ese nee cee see Seee ee cee «/ 


CSUACFC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char) rule_array, 
&verb_data_length, 
verb_data); 


if (return_code != 0) 


printf("Function Control Vector rejected for reason %d/%d\n\n", 
return_code, reason_code); 
return ERROR; /* Operation failed. */ 
} 


else 


printf("Loading Function Control Vector succeeded\n\n") ; 
printf("SAPI returned %1d/%ld\n\n", return_code, reason_code); 
return OK; 

} 

} 


Example: ILE RPG program for loading a function control vector 
for your 4758 Coprocessor 

Change this program example to suit your needs for loading a function control 
vector for your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 
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DARK R KKK KKK KK ERK KK EK KKK KR KKK KR KK KERR KK RRR KKK E RRR KERR KR ERR KKK 
D* LOAD_FCV 

Dx« 

D* Load the Function Control Vector into the 4758 card. 

D* The Function Control Vector enables the cryptographic 

D* functions of the 4758 card and is shipped with the 

Dx Cryptographic Access Provider products. 

Dx« 

D* The Function Control Vector is contained within a stream 

D* file. Before compiling and running this program, you 

D* must copy the contents of the stream file to a database 

D* member. An example of how to do this is shown in the 

D* instructions below for compiling and running this program. 
Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
D« (SC31-8609) publication. 

Dx 

D* Parameters: None 

Dx« 

D* Example: 

D* CALL PGM(LOAD_FCV) 

Dx« 

Dx Use these commands to compile this program on iSeries: 
Dx« 

D* CRTRPGMOD MODULE(LOAD_FCV) SRCFILE (SAMPLE) 

Dx« 

D* CRTPGM PGM(LOAD_FCV) MODULE(LOAD_FCV) 

D« BNDSRVPGM(QCCA/CSUACFC) 

Dx« 

Dx Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 
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DARK K KKK KKK KK ERK KEKE KKK KK R KKK RRR KERR RR RRR KERR RRR RR REE KERR ERRRERRRER 
PeeseSeee eee eee eee see see Sees Se SSeS eee eee Te 
D* Declare variables used by CCA SAPI calls 

D¥eeSSa oases seesasSeaaes eens Soa asa a- Sas ea sea see =e See = 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE 5 9B 0 

Dx ** Exit data length 

DEXITDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D« ** Verb data length 

DVERBDATALEN 5 9B @ INZ(204) 


Dx «x Verb data 


DVERBDATA S 204 

Peeateee ene sec cee ee cee sce see eee eee eee eee ese eee ese 

D* Declare variables for working with files 

Dees SeoeSese= ses S Sessa oSsasaaesae ae SSeS assess =-S—55——-5—55 

Dx ** File descriptor 

DFILED S 9B 0 

D* ** File path 

DPATH S 80 INZ('/QIBM/ProdData/CAP/FCV.CRT') 
Dx ** Open Flag - Open for Read only 

DOFLAGR S 101 @ INZ(1) 

Dx ** Structure of Funciton control vector file 
DFLD1 DS 

DFLDDTA 802 

DDESCR 391 470 

DFNCCTLVCT 471 674 

Dx ** Length of data read from file 

DINLEN S 9B 0 

Dx ** Declares for calling QDCXLATE API 

DXLTTBL S 10 INZ('QEBCDIC ') 

DTBLLIB S 10 INZ('QSYS ') 
DDESCLEN S 5P @ INZ(80) 

D* ** Index into a string 

DINDEX S 5B 0 

Dx xx Variable to hold temporary character value 
DCHAR 5 1 

Dx« 


DARK KKKKKK KK KEK KK KKK KKK ERK KKK KKK KKK KEKE KEK KEKE RRR RKE KKK ERERE 


D* Prototype for Cryptographic_Facilty_Control (CSUACFC) 


DAK RK KKK KKK KEK KKK KKK KK ERK KKK KKK KK RRR KERR KEK KEKE RRR ERK KR ERE 


DCSUACFC PR 

DRETCODE 9B 0 
DRSNCODE 9B 0 
DEXTDTALEN 9B 0 
DEXTDTA 4 
DRARRAYCT 9B 0 
DRARRAY 16 
DVRBDTALEN 9B 0 
DVRBDTA 204 

Dx« 


DA KRRKKKKKKK KER KKK KEKE KEKE RRR RRR KKK RRR RRR KEK KERR KERR ERK KR ERREER 
Dx Prototype for open() 

DA KRRKKAKK KK KEK KKK KEK KKK ERK KKK KKK KK R RK RRR KEK KEKE RRR ERK ERE 
Dx value returned = file descriptor (0K), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

D* Open flags 

D 9B @ VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U © VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 


DA KRKKKKKKKK KEK KKK KR KKK KERR KER KEK RRR RRR RRR KR RRR RK RRR RRR KEKE ERRERRERKEKRERE 
Dx Prototype for read() 

DA RRRK KKK KKK KEK KK KEK KKK ERK KKK KKK KK RR KKK KE KEK KEKE RRR RRR K KR ERREREK 

Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
D« File descriptor returned from open() 

D 9B @ VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be read 

D 9B @ VALUE 

Dx« 


DA KRAKK KKK KK KEK KKK KKK KKK RK KKK KKK KKK KEK KERR RRR KERR RR KR RRR K KK ER ERR REE ER 
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D* Prototype for close() 


DA RRA KKK KKK KK ERK KKK KKK KERR KERR KR KERR KK ERK RRR RRR REE RE RRR EK RR RE RRR RRR 
Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

D« File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

Pees Seece secs e sense tesee tee Seee See eee eee eee See eee ee eee 
Dx *x Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 
D¥eseeeessaslcssccssee se ses socoseSese sess SeScceossosScescssceesse]e 
DMSG S 80 DIM(4) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(80) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' -, 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

C* 

CR KKK KKK KEK KKK KEKE KKK KEK KKK EKER KKK ER KEK KKK ERR ER ERK RR EK ERE RK EKER E 
Cx START OF PROGRAM * 
Cx * 
CkXse Seed sie ces eee eee eee eee eee see es See eee e ee ee ec * 
Cx Open the FCV file * 
Gxeeeeo SSeS Season sees sae ee Sees aa a= == SS == = = == * 
Cx* Pumeccesaesecscotessacéoecee * 

Cx »** Null terminate path name * 

C* a a a a * 

C EVAL %SUBST(PATH:27:1) = X'Q0' 

C* feseeaseaeseSscccoe sess * 

Cx  »* Open the file * 

C* I a cs na a me em * 

C EVAL FILED = open(PATH: OFLAGR) 

Cx« Lssiasen saseeaeouen cesses * 

Cx  * Check if open worked « 

Cx* Se ee eee * 

C FILED IFEQ -1 

C* foaseaele naa eae eho ere ee Scat * 

Cx * Open failed, send an error message * 

Cx* tooo seseceSceeeeeeeesaasaesesceeesees * 

C MOVEL MSG (1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx* 

C ENDIF 

C* StS i pe lee ce ee ee rts * 

Cx * Open worked, read the FCV, and close the file * 

Cx* (asatia cee aeSseesee se seeeeaeeees oes sacs eeseeeeseeeee * 

C Z-ADD 802 INLEN 

C EVAL INLEN = read(FILED: FLDDTA: INLEN) 
C CALLP close (FILED) 

C* 

Cx* hasen= aeSseesee se See a saeeeeee ee eeeseeee * 

Cx * Check if read operation was OK * 

C* noc S asa Kaa aaa eee see ee * 

C INLEN IFEQ -1 

C MOVEL MSG (2) MSGTEXT 

C EXSR SNDMSG 

C RETURN 
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C* 
Cxkeseseeeeeeseeenese tec eSeeeeee eee Sete ee eee ee ee ese eee eee * 
Cx Copy the FCV to the verb data parameter. * 
CkeSeecseesesessesloesteSeoseees sesso Sse sass eeecao a= sae Seeese * 
C MOVEL FNCCTLVCT VERBDATA 

Ckee ee beeen seestess setae nese cas sense eee seen Son Shee See ees * 
Cx Convert description to EBCDIC and display it * 
CkeeeSescasesscssceeSeeSsssscessccesseosess sot eesSleese so cesece * 
C CALL "QDCXLATE' 

C PARM DESCLEN 

C PARM DESCR 

C PARM XLTTBL 

C PARM TBLLIB 

C MOVEL DESCR MSGTEXT 

C Z-ADD 80 INDEX 

CkeSaceceeaee sens lessoeeseiee sea Steams recess cee eosesscseeee ose ss * 
Cx Replace trailing null characters in description 

Cx with space characters. * 
Ckeeeesseesaseoseaesase ease psoas Se Sse a ae sea See eae ass eee ee se * 
C SETOFF 

C DOU *IN50 

C EVAL CHAR = %SUBST (MSGTEXT: INDEX: 1) 

C CHAR IFNE X'Q0' 

C SETON 

C ELSE 

C EVAL %SUBST(MSGTEXT: INDEX:1) = ' ' 

C SUB 1 INDEX 

C INDEX IFEQ 0 

C SETON 

C ENDIF 

C ENDIF 

C ENDDO 

C EXSR SNDMSG 
Oxkxereisesesesbeseessseek sce Seach ee Seo see eee a sesse ee aseestesees * 
Cx Set the keywords in the rule array * 
Ckseeoeec eee see socse see cose see eS Sees eee eee ese sees eeee esos * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "LOAD-FCV' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 


CR KKK KK KKK KKK KEKE KR KK ERK ER ERK KK EKER KER KER ERR EKER REE ERE REE ERRERE 


Cx Call Cryptographic Facilty Control SAPI 


CK KK KKK KKK KKK KR KR KEKE KK EK ERK KK RK ER KER KEK KERR ER ERK EKERERRRRRERE 


C CALLP CSUACFC (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C VERBDATALEN: 
C VERBDATA) 

Ge #eeocsscsoosseossoseesecece * 

Cx »* Check the return code * 

Ck “Kiser ee set eee ce ecescee see * 

¢ RETURNCODE IFGT 0 

Cx« Luca caecanasaeeansceses * 

Cx * Send failure message * 

Cx teseesseseasoasss—Soesee * 

C MOVEL MSG(3) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx* 

C ELSE 

C* 

Cx* tuesiacesacaceaeeecsseeces * 

Cx * Send success message * 


50 


50 


50 
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Cx kessSsccsseeessiessessoss: * 


C MOVEL MSG(4) MSGTEXT 

C EXSR SNDMSG 

Cc ENDIF 

Cx* 

C SETON LR 
C* 


CR KKK KKK EK KKK KEKE KKK KEKE RK EKER KEKE RE RR EKERRERERKEREREK ERR ER ERE 


Cx Subroutine to send a message 
CR KKK KKK KEK KKK KK KERR KK EK KKK ERE KKK KEK KEK KKK KERR EK ERK RR EK ERE RR EKER E 


C SNDMSG BEGSR 

C CALL "QMHSNDPM ' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
Cc PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 

Error trying to open FCV file. 

Error reading data from FCV file. 

CSUACFC failed with return/reason codes 9999/9999. 
The Function Control Vector was successfully loaded. 


Example: ILE C program for clearing a function control vector 
from your 4758 Coprocessor 

Change this program example to suit your needs for clearing a function control 
vector from your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


| a ee eee */ 
/* Clear the Function Control Vector from the 4758 card. */ 
/* The Function Control Vector enables the cryptographic */ 
/* functions of the 4758 card. Clearing it from the 4758 */ 
/* disabled the cryptographic functions. x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 2000 x/ 
/* */ 


/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly  ~*/ 


/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or x/ 
/* functions of these program. All programs contained */ 
/* herein are provided to you "AS IS". THE IMPLIED */ 
/* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A x/ 


/* PARTICULAR PURPOSE ARE ARE EXPRESSLY DISCLAIMED. IBM x/ 
/* provides no program services for these programs and files.*/ 


/* */ 
/* */ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* */ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CLEARFCV) x/ 
/* */ 
/* x/ 
/* Use the following command to compile this program: */ 
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/* CRTCMOD MODULE(CLEARFCV) SRCFILE(SAMPLE) x/ 


/* CRTPGM PGM(CLEARFCV) MODULE (CLEARFCV) x/ 
/* BNDSRVPGM(QCCA/CSUACFC) x/ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* - Cryptographic_Facility Control (CSUACFC) x*/ 
/* x/ 
/#aSeeseshasrsesesesseesee seeseeesteseeesensecoene sees seeseees */ 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 


void main(void) 
{ 
long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 
long verb_data_length; 
char *verb_data; 
char buffer[4]; 


teeee wae saee ees ees aoe ea see mes ane seSee see eS sa es a Sae =a > So sesaee */ 
/* No verb data is needed for this option. */ 
Jee tes weeeaeeeesasaesesesaeeaesaeesessenec see aaa eas) =e eee */ 


verb_data_length = 0; 
verb_data = buffer; 


[eeseecsaseusesssencseseassssssssessssessessassesssessessssecaeseccas «/ 
/* Rule array has two elements or rule array keywords */ 
feateeseteseeteseeteesese eee See ee eee tat ea ee sete eee cee See Seee eee */ 


rule_array_count = 2; 
memcpy ((char*)rule_array, "ADAPTERICLR-FCV ",16); 


[Seeseserasseesesatssessensasese sees S sees eeee es seneaeseeseserseecees */ 
/* Clear the Function control vector from the 4758 */ 
/ Posen wecessacsasseasecaecsnsstacs saseeassssesseseesseasssssssesssesS */ 


CSUACFC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char) rule_array, 
&verb_data_length, 
verb_data); 


if (return_code != 0) 
printf("Operation failed: return code %d : reason code %d \n", 
return_code, reason_code); 
else 
printf("FCV is successfullly cleared\n"); 
} 


Example: ILE RPG program for clearing a function control vector 
from your 4758 Coprocessor 
Change this program example to suit your needs for clearing a function control 


vector from your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 
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DARK R KKK KKK KK ER KKK KEK KKK ERK KKK KEK KKK RRR KEK KERR ER RK RRR KERR ERR KEKE 
D* CLEARFCV 

Dx« 

D* Clear the Function Control Vector from the 4758 card. 

D* The Function Control Vector enables the cryptographic 

Dx functions of the 4758 card. Clearing it from the 4758 

Dx disabled the cryptographic functions. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 

Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx« 

Dx Example: 

D* CALL PGM(CLEARFCV) 

Dx« 

D* Use these commands to compile this program on iSeries: 

D* CRTRPGMOD MODULE(CLEARFCV) SRCFILE (SAMPLE) 

D* CRTPGM PGM(CLEARFCV) MODULE (CLEARFCV) 


D« BNDSRVPGM(QCCA/CSUACFC) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 

D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 

Dx« 

DAR RAK KKK KKK KER KKK KEK KKK KKK KKK EK KKK RRR KERR KKK RRR RRR KERR RR RER RK RERE 
Pease Sceessosscsecsosscsscss cesses ssssosecessseoessssc 
D* Declare variables used on CCA SAPI calls 

DxeeeSese see ss see cee Sse see eee See see ee See ese 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

D* ** Exit data length 

DEXTTDATALEN Ss 9B 0 

D« «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

D* ** Rule array 

DRULEARRAY S 16 

D* ** Verb data length 

DVERBDATALEN S 9B 0 

D« «x Verb data 

DVERBDATA S 16 

Dx« 

Dx« 


DA RRR KKK KKK KK ERK KEKE KKK KR KRE KKK KR KKK KERR KERR KKK REE KEKE ER KEK REREKEE 


D* Prototype for Cryptographic_Facilty Control (CSUACFQ) 


DAK RAKKK KKK KK ER KEK KKK KKK KKK KKK KEK K RRR RK KKK KEK KR ERR KR ERK KERR 
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DCSUACFC PR 


DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 10 

Dx« 

Dkeeeceeceses alesse ceeesc sco ccceusseesesecssooeossoseosesssces 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
DkSeecassessescseceseeeSsosesssoeesseesssscoseees SeSce See sees] 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFATLRETC 4l 44 

DFATLRSNC 46 49 

Dx ** Variables required for the QMHSNDPM API 
DMESSAGEID S 7 INZ(' ") 
DMESSAGEFTILE S 21 INZ(' ') 
DMSGKEY Ss 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR KKK KK KK KKK KK EKER KR EKER KER ERK KK EKER KER KEK ERR EKER ERR EKER KERR ERR 
Cx START OF PROGRAM * 
Cx« * 
C¥esesesseeneedeccbeesees seen eheeeueenee eee eees eee eeeeeet ees * 
Cx Set the keyword in the rule array * 
OXee eee eewes een cuesees cesses eessoweenetensenensessesseeseeess * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "CLR-FCV ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

CktSeeteeteee secs she steSe ce esse ease eee oe eee * 
Cx Set the verb data length to 0 * 
Chae see eee eee eee see sete eee est eee eee eee eee ee eee ee * 
C Z-ADD 0 VERBDATALEN 

C¥eresesseene cece secscessensenssntceden eas eeeseeekoeecoueeHes * 
Cx Call Cryptographic Facilty Control SAPI 
CxkSesscsocasesisotscteateecsostecoee sees cece ssoseossSosScesse secs * 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT : 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 
Ckecesecsesesses-sssesess * 

Cx Check the return code 

Cxeossesesseseosecesosses * 

C RETURNCODE IFGT 0 

Cx* Pesecesococoseest cee cosas * 

Cx * Send a failure message * 

Cx Pececcteesrececceesescess * 

C MOVE MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx« 
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C ELSE 


Cx Assos eases leo e eee * 

Cx * Send a Success message * 

C* ees tt st eo ani el * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx 

C ENDIF 

C* 

C SETON LR 
C* 


CR KKK KKK KEK KKK KEKE KKK KERR EKER ERK RK EKER KEK ERR ER ERK RR EK ERE RR EKER 


Cx Subroutine to send a message 
CR KKK KKK EK KKK KKK KKK KEK KKK ERE KKK EKER KKK KERR EKER KER EKER ERR EKER 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx 


** 


CSUACFC failed with return/reason codes 9999/9999' 
The request completed successfully 


Load and set a master key 


After|“Load a function control vector” on page 74} you can load and set a master 


key. The 4758 Coprocessor uses the master key to encrypt all operational keys. The 
master key is a special key-encrypting key stored in the clear (not encrypted) 
within the 4758 Coprocessor secure module. Your 4758 Coprocessor uses the 
master key to encrypt other keys so that you can store those keys outside of your 
4758 Coprocessor. The master key is a 168—bit key formed from at least two 168-bit 
parts exclusive ORed together. 


Loading a master key 


There are three registers for your master keys: New, Current, and Old. The new 
master key register is used to hold a pending master key while it is being built. It 
is not used to encrypt any keys. The Current master key register holds the master 
key that is currently being used to encrypt newly generated /imported /re- 
enciphered keys. The old master key register holds the previous master key. It is 
used to recover keys after a master key change has occurred. When you load a 
master key, the 4758 Coprocessor places it into the New master key register. It 
remains there until you set the master key. 


Choose one of these three ways to create and load a master key, based on your 
security needs: 


* Load the first key parts and the subsequent key parts separately to maintain 
split knowledge of the key as a whole. This is the least secure method, but you 
can increase security by giving each key part to a separate individual. 


* Use random key generation, which will remove any human knowledge of the 
key. This is the most secure method for loading a master key, but you will need 
to clone this randomly generated master key into a second 4758 Coprocessor in 
order to have a copy of it. 
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* Use a pre-existing master key by cloning it from another Coprocessor. 


For more information on cloning master keys, see 


http: / /www.ibm.com/security /cryptocards/html/library.shtml a | 
Setting a master key 


Setting the master key causes the key in the Current master key register to move to 
the Old master key register. Then, the master key in the New master key register 
moves to the Current master key register. 


Note: It is vital for retrieval of data encrypted by the master key that you have a 
backup copy of the master key at all times. For example write it on a piece 
of paper, and make sure that you store the backup copy with appropriate 
security precautions. Or, clone the master key to another Coprocessor. 


The easiest and fastest way to load and set master keys is to use the 4758 
Cryptographic Coprocessor configuration web-based utility found off of the iSeries 
Tasks page at http://server-name:2001. The utility includes the Basic configuration 
wizard that is used when the Coprocessor is in an uninitialized state. If the 4758 
Coprocessor already has been initialized, then click on Manage configuration and 
then click on Master keys to load and set master keys. 


If you would prefer to write your own application to load and set master keys, 
you can do so by using the Master_Key_Process (CSNBMKP) API verb. Two 
example programs are provided for your consideration. One of them is written in 
ILE C, while the other is written in ILE RPG. Both perform the same function. 


“Example: ILE RPG program for loading a master key into your 4758 
Coprocessor” on page 90 


Note: If you choose to use one of the program examples provided, change it to 
suit your specific needs. For security reasons, IBM recommends that you 
individualize these program examples rather than using the default values 
provided. 


Re-encrypting keys 


When you set a master key, you should re-encrypt all keys that were encrypted 
under the former master key to avoid losing access to them. You must do this 
before you change and set the master key. 


You can re-encrypt keys in key store by using the 4758 Cryptographic Coprocessor 
configuration web-based utility found off of the iSeries Tasks page at 

http: / /server-name:2001. The 4758 Coprocessor must have already been initialized. 
Click on "Manage configuration” and then click on either "DES keys” to re-encrypt 
DES keys, or "PKA keys” to re-encrypt PKA keys. 


If you have keys that are not in key store or if you would prefer to write your own 
application to re-encrypt keys, you can do so by using the Key_Token_Change 
(CSNBKTC) or PKA_Key_Token_Change (CSNDKTC) API verbs. An example 
program is provided for your consideration. 


* |“Example: ILE C program for re-encrypting keys for your 4758 Coprocessor” on 
page 93 
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Note: If you choose to use the program example provided, change it to suit your 
specific needs. For security reasons, IBM recommends that you individualize 
these program examples rather than using the default values provided. 


Example: ILE C program for loading a master key into your 4758 
Coprocessor 

Change this program example to suit your needs for loading a new master key 
into your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


[xeeSe seeeanaee seo sees seeee = ee geese ease eo sees eae eeasseesece «/ 
/* Load a new master key on the 4758 card. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1, 5722-SS1 (C) IBM CORP. 1999, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* x/ 
/* Parameters: x/ 
/* OPTION (FIRST, MIDDLE, LAST, CLEAR, SET) x/ 
/*  KEYPART (24 bytes entered in hex -> X'O1F7C4....') */ 
/* Required for FIRST, MIDDLE, and LAST */ 
/* x/ 
/* Example: */ 
/* — CALL PGM(LOAD_KM) */ 
/* (FIRST X'Q123456789ABCDEFFEDCBA98765432100123456789ABCDEF' ) x/ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x/ 
/* x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(LOAD_KM) SRCFILE (SAMPLE) */ 
/* CRTPGM PGM(LOAD_KM) MODULE(LOAD_KM) */ 
/* BNDSRVPGM(QCCA/CSNBMKP QCCA/CSNBRNG) */ 
/* x/ 
/* Note: Authority to the CSNBMKP and CSNBRNG service programs */ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* The main Common Cryptographic Architecture (CCA) verb used x/ 
/* is Master_Key Process (CSNBMKP). x/ 
/* x/ 
[eseeeecste seed SeGen sees asseseee de eos aoe See c eee erates seoetees asc «/ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries x/ 


#include <stdio.h> 
#include <string.h> 
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#include <stdlib.h> 


(eceeieestaeese sess soseces So see sesh esse see eeceeHe sees see seeeceseeces «/ 
/* standard return codes */ 
| ee Se ee eee ee ee oe eee eee ee eee eae eee */ 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 
[xesasee sos scesesecssaastestassos cease ssa ssess sess sssse ss eeseeesssece «/ 
/* standard CCA parameters x/ 
[Reenee eset. eesti ees sese tees see seee se cece seers cesses «/ 


long return_code = 0; 

long reason_code = Q; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 1; 


[Saeeseeesssecsteaceesueasesecsseseasecs assess sess assess aso eseeesssece «/ 
/* parameters unique to this program x/ 
[Reeeeeeeseesee cece oe os eeesestesclesesse eee seep eeee pases reeset ose «/ 
char keypart[24]; /* Dummy parm for SET and CLEAR */ 
[sasaseeecsseestcecusansaestassesssasecsess ess sess csesesseesecessseae «/ 
/* Process the parameters x*/ 
| ee ee ee ee ae ee «/ 
if (argc < 2) 

{ 


printf("Option parameter must be specified.\n"); 
return(ERROR) ; 
} 


if (argc < 3 && memcmp(argv[1],"CLEAR",5) != 0 && 
memcmp(argv[1],"SET",3) != 0) 
{ 


printf("KeyPart parameter must be specified.\n"); 
return (ERROR) ; 


} 
J[Reseee ees eee sees eos eles see seeee eae eae ee ese oe cee eee ee eee ees «/ 
/* Set the keywords in the rule array */ 
|) Ree e ee eeaeesa sees ase s ae = sea eo saeoee a= a5=5 ose sae = Ses5e sea oe eee ease «/ 


memset (rule_array,' ',8); 
memcpy(rule_array,argv[1], 
(strlen(argv[1]) > 8) ? 8: strlen(argv[1])); 


| Raceeeeeresesas sem es ssae ee sseneeeaseaee na] == sae sees sesso seaoeeeaeeee «/ 
/* Call Master Key Process SAPI */ 
[Rese seseessseseseseesesceseen see seen pete eee eee «/ 
CSNBMKP( &return_code, 

&reason_code, 

&exit_data_length, 


exit_data, 

&rule_array_count, 

(unsigned char *)rule_array, 
(argc == 3) ? argv[2] : keypart); 


| $seaeeseeosease oes csenceieceneecesosseseoseseee Ee ses seteesesseoseaes «/ 
/* Check the return code and display the results */ 
| Reeteaseeesesa sas Soansacs Heese ese eceaee ae aseeeaaes ses sess se-essaee «/ 


if ( (return_code == OK) | (return_code == WARNING) ) 
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{ 
printf("Request was successful with return/reason codes: %d/%d \n", 
return_code, reason_code); 
return(0K) ; 
} 
else 
{ 
printf("Request failed with return/reason codes: %d/%d \n", 
return_code, reason_code); 
return (ERROR) ; 
} 


} 


Example: ILE RPG program for loading a master key into your 
4758 Coprocessor 

Change this program example to suit your needs for loading a new master key 
into your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DAKAR KKK KK KK ERK KEK KKK KK ERK KK RR KKK RRR RK RR KEKE RRR R RRR RRR ER ERR KERR 
D* LOAD_KM 

Dx 

D* Load a new master key on the 4758 card. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 


D* Parameters: 

Dx OPTION (FIRST, MIDDLE, LAST, CLEAR, SET) 
D* KEYPART (24 bytes entered in hex -> X'Q1F7C4....') 

D« Required for FIRST, MIDDLE, and LAST 

Dx« 

D* The master key is loaded in 3 or more parts. Specify FIRST 

D* when loading the first part, MIDDLE when loading all parts 

D* between the first and the last, and LAST when loading the final 

D* part of the master key. 

Dx« 

Dx As the master key parts are entered, they are Exclusively OR'ed 

D* with the current contents of the master key register. After the 
Dx last master key, if the contents do not have odd parity in every 
D* byte, a non-zero return/reason code will be returned. In order 

D* to ensure that the final result has odd parity, each key part 

D* should have odd parity in every byte. This is assuming that there 
D* is an odd number of key parts. (If there is an even number of 

D* key parts, then one of the key parts should have even parity). 

Dx« 

Dx A byte has odd parity if is contains: 

Dx an odd parity nibble: 1, 2, 4, 7, 8, B, D, or E 
D* an even parity nibble: 0, 3, 5, 6, 9, A, C, or F. 
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Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 


For example 32, A4, 1F, and 75 are odd parity bytes because 
they contain both an odd parity and an even parity 
nibble. 


05, 12, 6C, and E7 are even parity bytes because 
they contain either two even parity nibbles or 
two odd parity nibbles. 


The New master key register must be empty before the first part 
of a master key can be entered. Use CLEAR to ensure that the 
New master key register is empty before loading the master key 
parts. 


After loading the master key, use SET to move the master key from 
the New-master-key register to the Current-master-key register. 
Cryptographic keys are encrypted under the master key in the 

the Current-master-key register. 


Example: 
CALL PGM(LOAD_KM) (CLEAR) 


CALL PGM(LOAD_KM) 
(FIRST X'0123456789ABCDEFFEDCBA98765432100123456789ABCDEF' ) 


CALL PGM(LOAD_KM) 
(MIDDLE X'1032A873458010F7EF3438373132F1F2F4F8B3CDCDCDCEF1') 


CALL PGM(LOAD_KM) 
(LAST X'2040806789ABCDEFFEDC3434346432100123456789FEDCBA' ) 


CALL PGM(LOAD_KM) (SET) 


Use these commands to compile this program on iSeries: 
CRTRPGMOD MODULE(LOAD_KM) SRCFILE (SAMPLE) 


D* CRTPGM PGM(LOAD_KM) MODULE(LOAD_KM) 

D« BNDSRVPGM(QCCA/CSNBMKP) 

Dx 

D* Note: Authority to the CSNBMKP service program in the 
Dx QCCA library is assumed. 

Dx« 

D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Master_Key Process (CSNBMKP) 

Dx 

DAR RAKKKKKKK KEK KKK KKK KK ERK KKK KKK KK RR KKK ERK KEKE RRR RR E RK KERR KERR 
DxeSSeSSeesesseseSssesaoa ss Seeeasesoeasa see assess 

D* Declare variables for CCA SAPI calls 

Peeves as seatee se ee ace ak eee tees ee eeceeeSeeeie eee] 

Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXTTDATALEN S 9B 0 

Dx xx Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY Ss 16 

Dx ** Option (Rule Array Keyword) 

DOPTION S 8 

Dx xx Master key part parameter on program 
DMASTERKEY PART S 24 

D* xx Master key part parameter on CSNBMKP 
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DKEYPART S 24 INZ(*ALLX'Q0') 


Dx« 

DAKAR KKK KKK KK ERK KKK KKK KERR KERR KK KERR ER KERR KERR RRR RR ER KEK RREREREEK 
D* Prototype for Master_Key Process (CSNBMKP) 

DARK R KKK KKK KK ERE KK EK KKK KKK KKK KEK KKK RRR KERR KKK RE RRR RR KKK EREKK 
DCSNBMKP PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DMSTRKEY 24 OPTIONS (*NOPASS) 

Dx« 

De eee 
Dx ** Declares for sending messages to the 
D* ** job log using the QMHSNDPM API 

Peeiceseee sec ee sees een tee eee ee eee sees ee ese eee ceeseeeee, 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' r) 

DMSGTYPE S 10 INZ('*INFO ) 
DSTACKENTRY S 10 INZ('* *) 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(O) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 


CR KKK KKK EK KKK KK EK KEE K ER KERR ERE RK RK ER KERR ER ERR ER ERE RR EK ERE RR EKER 


C* 
C* 
C 


C* 
C* 
Cx* 
Cc 
C 
C* 


START OF PROGRAM 
*ENTRY PLIST 
PARM OPTION 
PARM MASTERKEYPART 
Set the keyword in the rule array 
MOVEL OPTION RULEARRAY 
Z-ADD 1 RULEARRAYCNT 
Check for FIRST, MIDDLE, or LAST 
OPTION IFEQ "FIRST! 
OPTION OREQ "MIDDLE' 
OPTION OREQ "LAST' 
Keen ee eee * 
* Copy keypart parameter * 
Keen ee ee * 
MOVEL MASTERKEYPART KEYPART 
ENDIF 
www ewe ew ew ew ee ee ee ee eee ee ee ee ee eee ee ee ee ee ee ee * 
Call Master Key Process SAPI * 
www ww em ew ew ee ew we ew ee ee eee eee ee ee eee ee ee ee ee ee eee * 
CALLP CSNBMKP (RETURNCODE: 
REASONCODE: 
EXT TDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
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* 
* 


** 


C RULEARRAY : 
C KEYPART) 
Cdeesessencesscencsscnces * 

Cx Check the return code * 

(kano e nee wee eee eee eee * 

C RETURNCODE IFGT 0 

Cx* ee ee * 

Cx * Send error message * 

Cx« tsacascucsaccaosesessos * 

C MOVE MSG(1) MSGTEXT 
C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 

Cx 

C ELSE 

Cx Vode seeses sess ese sees * 

Cx * Send success message * 

Cx* Set tS a i lp * 

C MOVE MSG (2) MSGTEXT 
C EXSR SNDMSG 

Cx* 

C ENDIF 

Cx 

C SETON LR 
Cx 


CR KKK KK EKER KK KEKE KR EKER KEK ERK KKK EKER KEKE RR ER ERR RR ERE RRR ERR ERE 


Cx Subroutine to send a message 
CR KKK KKK KKK KKK KKK RK KE KK KEK ERK KK EKER KERR RK ERR ERE RK RR ERE RRR ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


CSNBMKP failed with return/reason codes 9999/9999 
The request completed successfully 


Example: ILE C program for re-encrypting keys for your 4758 
Coprocessor 


Change this program example to suit your needs for re-encrypting keys for your 


4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
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Sree ee eee ete ee cece oreo eee Stee eee cee oseess */ 
Description: Re-enciphers key store files using the current ~*/ 
master key. */ 
*/ 

COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 
* 
/ 
This material contains programming source code for your */ 
consideration. These examples have not been thoroughly */ 
tested under all conditions. IBM, therefore, cannot */ 
guarantee or imply reliability, serviceability, or function ~*/ 
of these programs. All programs contained herein are x/ 
provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
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/* these programs and files. x/ 


/* */ 
/* Parameters: x/ 
/* char * keysto_type, choices are "DES" or "PKA" */ 
/* (If omitted, the default is "PKA".) */ 
/* Examples: x/ 
/* CALL PGM(REN_KEYSTO) PARM(DES) */ 
/* CALL PGM(REN_KEYSTO) */ 
/* */ 
/* Note: The CCA verbs used in the this program are more fully = */ 
/* described in the IBM 4758 CCA Basic Services Reference */ 
/* and Guide (SC31-8609) publication. */ 
/* */ 
/* Note: This program assumes the card you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* */ 
/* This program also assumes the key store file you will = */ 
/* use is already identified either by being specified on */ 
/* the cryptographic device or has been explicitly named = */ 
/* using the Key_Store Designate verb. Also you must be */ 
/* authorized to update records in this file. x/ 
/* x/ 
/* Use the following commands to compile this program: */ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(REN_KEYSTO) SRCFILE (SAMPLE) */ 
/* CRTPGM PGM(REN_KEYSTO) MODULE(REN_KEYSTO) x/ 
/* BNDSRVPGM(QCCA/CSNBKTC QCCA/CSNBKRL */ 
/* QCCA/CSNDKTC QCCA/CSNDKRL) */ 
/* */ 
/* Note: authority to the CSNDKTC, CSNDKRL, CSNBKTC, and CSNBKRL */ 
/* service programs in the QCCA library is assumed. */ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/*  PKA_Key_Token_Change (CSNDKTC) */ 
/* DES Key Token Change (CSNBKTC) */ 
/* PKA_Key Record List (CSNDKRL) x/ 
/* DES Key Record List (CSNBKRL) */ 
| Possebeeuscesseescsses setecsacsacseaesesss ses sessceS sel esceseesS */ 


#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 


/* Define the acceptable file types */ 

#define PKA 1 

#define DES 0 

int re_encipher(FILE *key_rec, long rec_length, int key type); 


int main(int argc, char *argv[]) 


{ 
[Reeseseesessesecesceesceasoen eee esses econ ne esaseaaeeseeeao */ 
/* standard return codes x/ 
[eeeoteabessese sesso csassscsscssesesesessaSestssssstSscsecess */ 


#define ERROR -1 
#define OK 0 
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long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 0; 
char exit_data[2]; 

long rule_array_count = 0; 
char rule_array[1] [8]; 


[Raeesseecsscesssesuesssseessese ase ssess= sso sesso sessseecse 


char key_label[65] = 
a ee a 
long data_set_name_length = 0; 
char data_set_name[65]; 
char security_server_name[9] = " “ 


FILE *kr1; 
int keysto_type = PKA; 


[Reece aceease ss asses ane aes sae sees deoe eS sas= as eesacs=es=essa5 


/* Check whether the user requested to re-encipher a DES or 
/* a PKA keystore file. Default to PKA if key file type is 


/* not specified. 
Wage st lee auc cen dk tcoueeeubcn dadeeceeaeceuaeseeeaus 
if (argc >= 2) 
{ 
if ((strcemp(argv[1],"DES")==0) ) 
{ 
printf("\nDES "); 
keysto_type = DES; 
} 


else if ((strcmp(argv[1] ,"PKA")==0) ) 
printf("\nPKA "); 

else 

{ 
printf("\nKeystore type parm incorrectly specified.\n"); 
printf("Acceptable choices are PKA or DES.\n"); 
printf("The default is PKA.\n"); 
return ERROR; 


} 


else 


{ 
printf("\nPKA "); 
} 


if (keysto_type == DES) 


{ 
| Raeee ee ceese saesan sense mes See sseees sess essees=as-—s555=a45=e5 */ 
/* Invoke the verb to create a DES Key Record List x/ 
[¥osesecsbsseeasaeeeoSascses see lee seca eenSeoeaaeeen oon thsseses */ 


CSNBKRL( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_label, 
&data_set_name_length, 
data_set_name, 
security server_name) ; 

} 
else 


{ 
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/* Invoke the verb to create a PKA Key Record List */ 


CSNDKRL( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
key_label, 
&data_set_name_length, 
data_set_name, 
security server_name) ; 


} 
if ((return_code != 0) || (reason_code != @)) 
{ 
printf("Key Record List generation was unsuccessful. "); 
printf("Return/reason code = %d/%d\n", return_code, reason code); 
} 
else 


{ 
printf("Key Record List generation was successful. "); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
data_set_name[data_set_name_length] = '\0'; 
printf("data_set_name = %s\n",data_set_name) ; 


/* Open the Key Record List file. */ 
kr] = fopen(data_set_name, "rb"); 


if (kr] == NULL) /* Open failed. */ 
{ 


printf("The open of the Key Record List file failed\n"); 
return ERROR; 
} 
else /* Open was successful. */ 
{ 
char header1[77]; 
int num_rec, i; 
long rec_length, offset_recl; 


/* Read the first part of the KRL header. */ 
fread(headerl,1,77,kr1); 


/* Get the number of key records in the file. */ 
num_rec = atoi(&header1[50]); 
printf("Number of key records = %d\n",num_rec) ; 


/* Get the length for the key records. */ 
rec_length = atol (&header1[58] ); 


/* Get the offset for the first key record. */ 
offset_recl = atol(&header1[62]); 


/* Set the file pointer to the first key record. */ 
fseek(kr1, offset_recl, SEEK_SET); 


/* Loop through the entries in the KRL and re-encipher. */ 
for (i = 1; i <= num_rec; i++) 
{ 
int result; 
result = re_encipher(kr1, rec_length, keysto_type); 
if (result !=0) 
{ 
fclose(kr1); 
return ERROR; 
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} 


printf("Key store file re-enciphered successfully.\n\n"); 


fclose(kr1); 
return OK; 


} 
} 


} /* end of main() */ 


int re_encipher(FILE *key_rec, long rec_length, int key_type) 


{ 


/Resesee Sos sc es cseceesnesestassesssasess assess sesssssesesecss */ 
/* standard CCA parameters x/ 
| Reeeeeeesesesee Sao Sees Ge teeescece ste eseeaeeeeerse se ee seers */ 


long return_code; 
long reason_code; 
long exit_data_length 
char exit_data[2]; 
long rule_array_count 
char rule_array[1] [8]; 


long key_identifier_length = 64; 


char key_identifier[64] ; 
char key_record[154] ; 


fread(key_ record, 1, rec_length, key_rec); 
memcpy(key_identifier, &key_record[3], 64); 


memcpy(rule_array, "RTCMK 


if (key_type == DES) 
{ 
CSNBKTC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
key_identifier); 


} 
else if (key_type == PKA) 


CSNDKTC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
&key_identifier_length, 
key_identifier); 

} 
else 


{ 


"¥8); 


printf("re_encipher() called with an invalid key type.\n"); 


return ERROR; 
} 


printf("Re-enciphering for key_label = %.64s",key_ identifier) ; 
printf("completed with return/reason codes of "); 


Chapter 4. 4758 Cryptographic Coprocessor for iSeries 


97 


printf ("%d/%d\n", return_code, reason_code) ; 
return return_code; 


}/* end of re_encipher() */ 


Configure the 4758 Cryptographic Coprocessor for use with 
DCM and SSL 


The following section lists the steps needed to make the 4758-023 Coprocessor 
ready for use with SSL. 


Using your 4758-023 Coprocessor with DCM and SSL 


To install the 4758-023 Coprocessor and prerequisite software, you must do the 
following: 


* Install the Coprocessor in your server. 


For feature 4801, install your 4758-023 Coprocessor, as instructed in the 4801 PCI 
Cryptographic Coprocessor Card Instructions that are shipped with your 
4758-023 Coprocessor. 


For feature 4802, ask your IBM hardware service representative to install your 
4758-023 Coprocessor. 


* Install OS/400 Option 35 CCA CSP. 


* Install either the 5722-AC3 Cryptographic Access Provider 128-bit licensed 
program product. 


* Set OS/400 object authorities for|“Secure access to the 4758 Cryptographic 


* Use your web browser to go to the iSeries Tasks page at http:/ /server-name:2001. 


* Configure the 4758 by following the steps in|“Configure the 4758 Cryptographic 


The 4758-023 Coprocessor is now ready to be used to create private keys for SSL 
certificates. 


* Use DCM to create a certificate, specifying that the private key be generated by 
the hardware. 


* Use DCM to receive the signed certificate. 


See |Manage public Internet certificates for SSL communications sessions|for more 


information on these last two steps. 

Note: If you plan to use multiple cards for SSL, see|“Manage multiple 4758 
Cryptographic Coprocessors” on page 182}and |“Clone master keys” on 
page 192 


Configure the 4758 Cryptographic Coprocessor for use with 
OS/400 applications 


The following section lists the steps needed to_make the 4758-023 Coprocessors 


ready for use with a OS/400 application. See|Cryptographic hardware scenario: 


rite an OS/400 application to use the 4758 Cryptographic Coprocessor| 


example usage of the 4758 Cryptographic Coprocessor in an OS/400 application. 


Using the 4758-023 Coprocessor for OS/400 applications 


To install the 4758 Coprocessor and prerequisite software, you must do the 
following: 
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Install the Coprocessor in your server. 


For feature 4801, install your 4758 Coprocessor, as instructed in the 4801 PCI 
Cryptographic Coprocessor Card Instructions that are shipped with your 4758 
Coprocessor. 


For feature 4802, ask your IBM hardware service representative to install your 
4758 Coprocessor. 


Install OS/400 Option 35 CCA CSP. 


* Install either the 5722-AC3 Cryptographic Access Provider 128-bit or the 
5722-AC2 Cryptographic Access Provider 56-bit licensed program product. 


* Set OS/400 object authorities for|“Secure access to the 4758 Cryptographic 
Coprocessor” on page 20 
* Use your web browser to go to the iSeries Tasks page at http:/ /server-name:2001. 


* Configure the 4758 by following the steps in|“Configure the 4758 Cryptographic 
Coprocessor” on page 23 


* Write your application to use the Cryptographic Coprocessor. 


Note: If you plan to use multiple cards for your OS/400 applications, see|“Manage| 


Migrate to the 4758 Cryptographic Coprocessor 


This information explains how to perform the following migrations: 
¢ |Migrate from other iSeries c 


* |Migrate key store files 


Migrate from other iSeries cryptographic products to the 4758 
Cryptographic Coprocessor 


If you have worked with cryptography before, you may have one of two 
cryptographic products on your server. You may have key store files from the IBM 
CCA Services for iSeries (5799-FRF) product. Or, you may have cryptographic 
cross-domain files from Cryptographic Support for iSeries (5769-CR1). If this is the 
case, you can migrate their contents to your new 4758 Coprocessor. There is an 
example migration program available for each cryptographic product: 


* IBM CCA Services for iSeries (5799-FRF). This product provides cryptographic 
function on cryptographic hardware by using Data Encryption Standard (DES). 
The Common Cryptographic Architecture (CCA) Services requires that you have 
a cryptographic processor, feature number 2620 or 2628, installed on your server. 


You can migrate key store files from the IBM CCA Services to your 4758 
Coprocessor using}“Migrate key store files from the IBM CCA Services for 

* Cryptographic Support for iSeries (5769-CR1 or 5722—CR1). Cryptographic 
Support is a software-only product that encrypts cross-domain keys under a host 


master key. Cryptographic Support then stores the cross-domain keys in a file. 
You can migrate cross-domain key files from Cryptographic Support for iSeries 


server to your 4758 Coprocessor using |“Migrating Cryptographic Support for 
iSeries cross-domain key files” on page 109 


Migrate key store files from the IBM CCA Services for iSeries 
If you currently use the Common Cryptographic Architecture (CCA) Services for 
iSeries (5799-FRF), you can migrate the keys in the key store file so that your 4758 
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Coprocessor can use them. The Coprocessor uses the migrated keys with the CCA 
Cryptographic Service Provider (CCA CSP, which is packaged as OS/400 Option 
35), 


Note: You cannot migrate all keys because the CCA Services supports a wider 
range of key types than the 4758 Coprocessor. For example, you cannot 
migrate keys that have had the prohibit-export bit in the control vector set. 
Also, you cannot migrate any of the PKA keys in the CCA Services for 
iSeries because CCA Services provides public key algorithm (PKA) support 
that is significantly different than that in the 4758 Coprocessor. 


You will need to write two programs to migrate your Data Encryption Standard 
DES) keys. Or, there are two program examples, and 
which you can change and run to 
migrate the key store files. The CCA defines the format of the external DES key 


tokens and therefore is the same for both products. 


Use the EXPORT program in conjunction with the IMPORT program. This will 
migrate DES keys from the IBM CCA Services for iSeries to your 4758 Coprocessor 
and CCA CSP. You should run the EXPORT program first to generate a file that 
contains the necessary key information in a secure, exportable form. You should 
then transfer the file to the target server. You can then run the IMPORT program to 
import the keys from the file into a key storage file that you have created. The key 
storage file to which you want to import the keys must already exist before you 
run the program. 


To change the program examples, follow these steps. 

1. Import the same clear key value for a key-encrypting key into both products. 
For the CCA Services, the key-encrypting key must be an EXPORTER, and for 
CCA CSP it must be an IMPORTER. 

2. Run the Key_Export (CSNBKEX) CCA API in the CCA Services for each key 
you want to migrate. This causes the program example to call an API. 

3. Import the outputted external key token into CCA CSP and your 4758 
Coprocessor by using the Key_Import (CSNBKIM) CCA API. Remember to 
change the program to do this for each key. 


Once you change the program to address each key, you can run the program. 
Remember to run EXPORT first and then IMPORT. 


Note: If you choose to use the program examples provided, change them to suit 
your specific needs. For security reasons, IBM recommends that you 
individualize these program examples rather than using the default values 
provided. 


Example: EXPORTing keys: This is step one. Change this program example to 


suit your needs for migrating the key store files. Once you run this program, use 
“Example: IMPORTing keys” on page 105}to complete the migration process. 


[#esaesenseaeeses oss saeee ese ce sae assesses nae aeosees sere ssoea-ce= */ 
/* Description: One of two programs used to migrate DES keys x*/ 
/* from a key store file used with the 2620 toa */ 
/* key store file for use with the 4758. */ 
/* */ 
/* Note: This program is intended to be used in conjunction with */ 
/* IMPORT_TSS to migrate DES keys from 2620 to 4758. */ 
/* EXPORT_TSS should be run first to generate a file */ 
/* containing the needed key information in a secure, */ 
/* exportable form. The file should then be transferred */ 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 
#i 
#i 
#i 
#i 


in 


#d 
#d 


to the target system. IMPORT_TSS can then be run using */ 


the file to import the keys into a previously created */ 
key storage file. x/ 
*/ 
*/ 
COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 
* 
/ 
This material contains programming source code for your */ 
consideration. These examples have not been thoroughly */ 
tested under all conditions. IBM, therefore, cannot */ 
guarantee or imply reliability, serviceability, or function ~*/ 
of these programs. All programs contained herein are x/ 
provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
these programs and files. x/ 
* 
/ 
Parameters: File to contain exported key information x/ 
* 
/ 
Examples: x/ 
CALL PGM(EXPORT_TSS) PARM('File_for_Exported_Keys') */ 
* 
/ 
x/ 
Use the following commands to compile this program: x/ 
ADDLIBLE LIB(QTSS) */ 
CRTCMOD MODULE(EXPORT_TSS) SRCFILE (SAMPLE) */ 
CRTPGM PGM(EXPORT_TSS) MODULE(EXPORT_TSS) x/ 
* 
/ 
Note: authority to the functions CSNBKEX, CSNBKPI, CSNBKRL, */ 
and CSNBKTB is assumed */ 
* 
/ 
Common Cryptographic Architecture (CCA) verbs used: x/ 
Key_Export CSNBKEX */ 
Key_Part_Import CSNBKPI x/ 
Key_Record_List CSNBKRL x/ 
Key_Token_Build CSNBKTB */ 
ee ea ee ee ee eee ee a ee ee eee */ 
nclude <stdlib.h> 
nclude <stdio.h> 
nclude <string.h> 
nclude "MIPTRNAM.H" /* needed to resolve function ptrs */ 
nclude "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 
t main(int argc, char *argv[]) 


{#eseveesessosesseeessesscsretcosesdeen eases */ 
/* standard return codes x/ 
JBoss ceesacssessesectesssses-cessseesssassssessosees «/ 
efine ERROR -1 

efine OK 0 

| Heme aan see san ee aaa eae eaeee aes sessed eee sees = ee=e */ 
/* Declare function pointers (see csucincl.h) */ 
j fees eae sise acess sess =eeeesaeessesecedeseas=eseseae */ 


T_CSNBKEX *CSNBKEX; 
T_CSNBKRL *CSNBKRL; 
T_CSNBKPI *CSNBKPI; 
T_CSNBKTB *CSNBKTB; 


(esse enseesesesseeeesssssecoetetee sean eee «/ 
/* standard CCA parameters x/ 
JRosseeosssssessescousesese sce scsessseqssssenseseas */ 
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long return_code; 
long reason_code; 


long exit_data_length = 0; 

char exit_data[2]; 

long rule_array_count = 0; 

char rule_array[2] [8]; 
Jeosecesescasescaseesessassssssessesses ssessessesous */ 
/* additional parameters needed for CSNBKRL */ 
[#osectsecessescassssesscsoessesnscesecescsscsslssess */ 


char key_label [64]; 
long data_set_name_length = 0; 
char data_set_name[65]; 


char security_server_name[9] = " me 

[Rosset sacsass sos sesceteresoeeoesseeseeeeeeseceescae */ 
/* additional parameters needed for CSNBKEX */ 
| dGxecestessseseesseseesessesncssssssas-selsecsSefae */ 


char key_type[8]; 

char source_key_identifier[64]; 
char exporter_key_identifier[64]; 
char target_key_token[64]; 


[#e@armeaceassseesesseese css ceaseaesses sees oeseo—s5 */ 
/* additional parameters needed for CSNBKTB */ 
[RSesesscesese=ascehseesessssn oa aeeaee ee seese eee */ 


char key_token[64] ; 

char key_value[64]; 

long master_key_verification_pattern = 0; 
long reserved_int; 

char reserved _str[8]; 

char control_vector[16]; 


[kiees se ceStese tena eeserseeeseaecasseeeetesescesese «/ 
/* additional parameters needed for CSNBKPI */ 
[ees seseseseete-seceecadeeSaeren oe ssesse sc eseseseeccae «/ 


char key_part[16]; 
char key_identifier[64]; 


[eeseeececeeesaseeeeee seeped sae Seo eeeeencee «/ 
/* Other variables */ 
| Meese Sera aes eeeesseres—saee—seers sas soo =sSe5eesa5 */ 


char header1[77]; 

long num_rec, i; 

long num_successful = 0; 

long rec_length, offset_recl; 


char key_record[154]; 


FILE *kr1, *export_file; 


/* Check input parm */ 

if (argc < 2) 

{ 
printf("File for storing the exported key data not specified.\n"); 
return ERROR; 


} 

(#esonmeaces ae aeeensceaae sssae=ee— esses aso seaeeescers «/ 
/* Resolve function pointers */ 
[xkesbessacseosasscesccseceenseeesee sees seoeeeeecenss «/ 


_lib_qualify(CSNBKEX,QTSS) 
_lib_qualify(CSNBKRL,QTSS) 
_lib_qualify(CSNBKPI,QTSS) 
_1ib_qualify(CSNBKTB,QTSS) 
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memset (key_label,' ',64); 
memcpy (key_label,"*.*.*.*.*",9); 


[RasesreseaSeesesesece sees ssesseessseeudeseeeeesessesseseceS */ 
/* Invoke the verb to create a DES Key Record List */ 
j $eteeseesaeeccscsa= sea seessee see s= see e eae aes ses aes */ 


CSNBKRL( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_label, 
&data_set_name_length, 
data_set_name, 
security_server_name) ; 


if ((return_code != 0) || (reason_code != @)) 

{ 
printf("Key Record List generation was unsuccessful. "); 
printf("Return/reason code = %d/%d\n",return_code, reason_code); 
return ERROR; 


} 

printf("Key Record List generation was successful. "); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
data_set_name[data_set_name_length] = '\0'; 


printf("data_set_name = %s\n\n",data_set_name) ; 


/* Generate a clear key for export use. */ 
/* The same key will be used for import. «/ 
memcpy (key_type, "EXPORTER",8) ; 
rule_array_count = 2; 

memcpy (rule_array[0],"INTERNAL",8) ; 

memcpy (rule_array[1],"KEY-PART",8) ; 


CSNBKTB( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_token, 
key_type, 
&rule_array_count, 
(char *) rule_array, 
key_value, 
&master_key_verification_pattern, 
&reserved_int, 
reserved str, 
control_vector, 
reserved str, 
&reserved_int, 
reserved str, 
reserved str); 


if (return_code != 0) { 
printf("Building of the export key failed.\n"); 
printf("Key Token Build failed."); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
return ERROR; 
} 


/* Import the key parts to be used. */ 
rule_array_count = 1; 
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memcpy(rule_array[0],"FIRST ",8); 
memset (key_part,'\x01',16); 


for(i=l;i<=2;i++) { 

CSNBKPI( &return_code, 
&reason_code, 
&exit_data_length, 
(char *) exit_data, 
&rule_array_count, 
(char *) rule_array, 
key_part, 
key_token) ; 


if (return_code != 0) { 
printf("Building of the export key failed.\n"); 
printf("Key Part Import failed."); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
return ERROR; 
} 


memcpy (rule_array[0], "LAST ".8); 

/* Set key part to the clear key to be used. */ 
/* Note: It may not be desirable to hard-code this. */ 
memcpy (key_part,"ClEar.KEY.hErE!!",16); 


} 


/* Export key built successfully. */ 
/* Open the Key Record List file. */ 
kr1 = fopen(data_set_name, "rb"); 


if (kr1 == NULL) 

{ /* Open failed. */ 
printf("The open of the Key Record List file failed.\n"); 
return ERROR; 


/* Key record list open was successful. */ 
/* Open the file to save key info. */ 
export_file = fopen(argv[1], "wb"); 
if (export_file == NULL) 
{ 
printf("Opening of key export file failed.\n"); 
fclose(kr1); 
return ERROR; 
} 


/* Write num_successful to the export file to hold a place for it. */ 
fwrite(&num_successful,sizeof (long) ,1,export_file); 


/* Read the first part of the KRL header. */ 
fread(header1,1,77,kr1); 


/* Get the number of key records in the file. */ 
num_rec = atoi(&header1[50]); 
printf("Number of key records = %d\n",num_rec); 


/* Get the length for the key records. */ 
rec_length = atol (&header1[58]) ; 


/* Get the offset for the first key record. */ 
offset_recl = atol (&header1[62]); 


/* Set the file pointer to the first key record. */ 
fseek(krl, offset_recl, SEEK_SET); 
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/* Set the key type to TOKEN. */ 
memcpy(key_type,"TOKEN ",8); 


/* Loop through the entries in the KRL and EXPORT. */ 
for (i = 1; i <= num_rec; i++) 
{ 

fread(key_record, 1, rec_length, kr1); 

memcpy (source_key_identifier, &key_record[3], 64); 


CSNBKEX(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_type, 
source_key_identifier, 
key_token, 
/* exporter_key_identifier, */ 
target_key_token); 


printf("Exporting of key = %.64s",source_key identifier); 
printf("completed with return/reason codes of "); 
printf ("%d/%d\n", return_code, reason_code) ; 


if (return_code == 0) 

{ 
++num_successful ; 
fwrite(source_key_identifier, 1, 64, export_file); 
fwrite(target_key_token, 1, 64, export_file); 

} 


} /* end of for loop */ 


printf("Key store file exported successfully.\n"); 
printf("%d key(s) successfully exported.\n\n",num successful) ; 


/* Write out the number of exported keys and close the file. */ 
fseek(export_file,0,SEEK_SET); 
fwrite(&num_successful ,sizeof(long),1,export_file); 


/* Close the files and return. */ 
fclose(kr1); 

fclose(export_file); 

return OK; 


} 


Example: IMPORTing keys: This is step two. If you have not already done so, 


run the |“Example: EXPORTing keys” on page 100] program to begin the migration 


process. Then change this program example to suit your needs for completing the 
migration of the key store files. 


| en eee ee */ 
/* Description: One of two programs used to migrate DES keys x/ 
/* from a key store file used with the 2620 toa */ 
/* key store file for use with the 4758. x/ 
/* x/ 
/* Note: This program is intended to be used in conjunction with */ 
/* EXPORT_TSS to migrate DES keys from 2620 to 4758. */ 
/* EXPORT_TSS should be run first to generate a file */ 
/* containing the needed key information in a secure, x/ 
/* exportable form. The file should then be transferred */ 
/* to the target system. IMPORT_TSS can then be run using */ 
/* the file to import the keys into a previously created */ 
/* key storage file. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 
#i 
#i 
#i 


/* 
/* 
/* 
/* 
/* 


st 


iSeries: Cryptographic 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these programs. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 
Parameters: File containing exported key information 
Examples: 
CALL PGM(IMPORT_TSS) PARM('Exported_Key File') 
Note: The CCA verbs used in the this program are more fully 


described in the IBM 4758 CCA Basic Services Reference 
and Guide (SC31-8609) publication. 


Note: This program assumes the card you want to use is 
already identified either by defaulting to the CRPO1 
device or has been explicitly named using the 
Cryptographic_Resource Allocate verb. Also this 
device must be varied on and you must be authorized 
to use this device description. 


This program also assumes the key store file you will 
use is already identified either by being specified on 
the cryptographic device or has been explicitly named 
using the Key Store Designate verb. Also you must be 
authorized to update records in this file. 


Use the following commands to compile this program: 
ADDLIBLE LIB(QCCA) 
CRTCMOD MODULE(IMPORT_TSS) SRCFILE (SAMPLE) 
CRTPGM PGM(IMPORT_TSS) MODULE(IMPORT_TSS) 
BNDSRVPGM(QCCA/CSNBKRC QCCA/CSNBKIM QCCA/CSNBKPI) 


Note: authority to the CSNBKIM, CSNBKPI, and CSNBKRC 
service programs in the QCCA library is assumed. 


Common Cryptographic Architecture (CCA) verbs used: 
Key_Import CSNBKIM 
Key_Record_Create CSNBKRC 
Key_Part_Import CSNBKPI 


nclude <stdlib.h> 
nclude <stdio.h> 
nclude <string.h> 


nclude "csucincl.h" /* header file for CCA Cryptographic 


Service Provider for iSeries 


*/ 


Structure defining the DES key token for internal keys. This */ 


structure is used in the creation of the importer key- 
encrypting key. For more information on the fields in this 
structure, see the IBM 4758 CCA Basic Services Reference and 
Guide (SC31-8609-01), Appendix B and C. 


ruct DES_key_token { 
char type; /* Set to 0x01 for 'internal' 
char resvl; /* Reserved (set to binary zero) 
char mkvp[2]; /* Master Key Verification Pattern 
char version; /* Version. Will be set to 0x03. 
char resv2; /* Reserved (set to binary zero) 
hardware 


*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 


char flag; /* 
char resv3; /* 
char resv4[8]; /* 
char key1[8]; /* 


char key2[8]; /* 
int cvb1[2]; /* 


int cvb2[2]; /* 


char resv5[12]; /* 
int tv; /* 


}3 


int main(int argc, char *argv[]) 


#define ERROR -1 
#define OK 0 


long return_code; 
long reason_code; 


long exit_data_length = 0; 
char exit_data[2]; 
long rule_array_count = 0; 


char rule_array[2] [8]; 


char import_key_label [64]; 
char import_key_token[64]; 


Flag 

Reserved (set to binary zero) 
Reserved (set to binary zero) 
Single length encrypted key or 
left half of double length 
encrypted key. 

Null or right half of double 
length encrypted key 
Control-vector base 

Null or control vector base for 
the 2nd eight-byte portion of a 
16-byte key 

Reserved (set to binary zero) 
Token-validation value 


struct DES_key_token importer_kt; 


char importer_key_token[64] ; 
char key_type[8]; 
char key_part[16]; 


long num_rec = 0, i; 
long num_imported = 0; 


FILE *import_file; 
printf("\n\n"); 


/* Check input parm */ 
if (argc < 2) 
{ 


printf("File containing the 


Chapter 4. 4758 Cryptographic Coprocessor for iSeries 


*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


exported key data not specified. \n"); 


107 


return ERROR; 
} 


/* Generate a clear key for import use. */ 


/* Initialize the importer key token. */ 

memset (&importer_kt,0x00,sizeof(struct DES_key_token)); 
importer_kt.type = 0x01; 

importer_kt.version = 0x03; 

importer_kt.flag = 0x40; /* Indicates control vector is present */ 


importer_kt.cvb1[0] = 0x00427d00; 
importer_kt.cvbl[1] = 0x03480000; 
importer_kt.cvb2[0] = 0x00427d00; 
importer_kt.cvb2[1] = 0x03280000; 


importer_kt.tvv = Ox0af53a00; 


/* Initialize parameters for the first pass */ 
rule_array_count = 1; 
memcpy(rule_array[0],"FIRST ",8); 

memset (key_part,0x01,16); 


for(i=1;i<=2;it++) { 

CSNBKPI( &return_code, 
&reason_code, 
&exit_data_length, 
(char *) exit_data, 
&rule_array_count, 
(char *) rule_array, 
key_part, 

(char *) &importer_kt); 


if (return_code != 0) { 
printf("Building of the importer key failed.\n"); 
printf("Key Part Import failed."); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
return ERROR; 


} 

else if (i == 1) { 
/* Init variables for the final pass */ 
memcpy (rule_array[0] , "LAST mB). 
/* Set key part to the clear key to be used. */ 
memcpy (key_part,"ClEar.KEY.hErE!!", 16); 

} 

} 


/* Import key built successfully. */ 
printf("Importer key built successfully.\n\n"); 


/* Open the Exported Key file. */ 
import_file = fopen(argv[1], "rb"); 


if (import_file == NULL) 

{ /* Open failed. */ 
printf("The open of the Exported Key file failed\n"); 
return ERROR; 

} 


/* Import Key file open was successful. */ 
fread(&num_rec,sizeof(num_rec),1,import_file); 


/* Loop through the entries in the import file and create key records. */ 
for (i = 1; i <= num_rec; i++) 
{ 

fread(import_key_label, 1, 64, import_file); 

fread(import_key_token, 1, 64, import_file); 
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printf("Importing DES key:\n"); 
printf (" \"%.64s\"\n", import_key_label); 


/* Create a key record. */ 

CSNBKRC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
import_key_label); 


if (return_code != 0) 


{ 


printf(" Key record creation failed. "); 
printf("Return/reason codes = %d/%d\n\n", return_code, reason_code) ; 
continue; 


} 


/* Else, key record created successfully so import the key. */ 
memcpy(key_type,"TOKEN ",8); 


CSNBKIM( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_type, 
import_key_token, 
(char *) &importer_kt, 
import_key_label); 


if (return_code != 0) 


{ 


printf (" Key import failed. "); 
printf("Return/reason codes = %d/%d\n\n", return_code, reason_code) ; 
continue; 


} 


/* else, Key import was a success. */ 
printf (" Key imported successfully. "); 
printf("Return/reason codes = %d/%d\n\n",return_code,reason_code) ; 
++num_imported; 
} /* end of for loop */ 


printf("\nCompleted key import procedure. \n"); 

printf("%d of %d key(s) successfully imported.\n\n",num_imported,num_rec) ; 
fclose(import_file); 

return OK; 


} 


Migrating Cryptographic Support for iSeries cross-domain key 
files 

If you have worked with cryptography before on your server, you may have 
cryptographic cross-domain files from Cryptographic Support for iSeries 
(5769-CR1). You can migrate existing cross-domain keys to your new 4758 
Coprocessor. 


The Cryptographic Support for iSeries product (5769-CR1 or 5722—CR1) encrypts 
its cross-domain keys under the host master key and stores them in a file. 
Common Cryptographic Architecture (CCA) cannot use them in this form, but you 
can migrate them from the Cryptographic Support product for the CCA to use 
with your Coprocessor. You must consider a number of things before completing 
this task: 
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* Encryption of cross-domain keys by cross-domain keys. Cryptographic Support 
for iSeries supports importing clear key values for cross-domain keys and 
encrypting data keys under cross-domain keys. However, it does not support 
encrypting cross-domain keys under cross-domain keys, nor does it support 
returning the clear key value of any cross-domain key. Because of this, migrating 
cross-domain keys is considerably more involved than just performing an export 
and import operation. 


* Single-length keys versus double-length keys. All keys in Cryptographic 
Support for iSeries are single-length keys. In CCA, all key-encrypting keys and 
PIN keys are double-length keys. Although the key lengths are different, you can 
build a double-length key from a single-length key and have that double-length 
key behave like the single-length key. If both halves of a double-length key are 
the same, the result of any encryption operation will be the same as if a 
single-length key was used. Therefore, when you migrate keys from 
Cryptographic Support for iSeries to CCA, you will need to copy the key value 
of the cross-domain key into both halves of the key value for a CCA key. 


* CCA control vectors versus master key variants. In CCA, when a key is said to 
be encrypted under a key-encrypting key, it is really encrypted under a key that 
is formed by an exclusive OR operation of the key-encrypting key and a control 
vector. For Cryptographic Support, cross-domain keys are encrypted under one 
of three different master key variants. A master key variant is the result of the 
exclusive OR operation of the host master key with either 8 bytes of 
hexadecimal 22, 44, or 88. Both control vectors and master key variants provide 
key separation and thereby restrict keys to their intended use. In CCA, the value 
of the control vector determines its use. In Cryptographic Support how a key is 
used determines which master key variant will be used to decrypt it. In both 
cases, any attempt to use the key for other than its intended use will result in an 
error. Although control vectors and master key variants may work similarly, the 
values used to form master key variants are not the same as control vectors. 


* Asymmetry of CCA control vectors for double-length keys. Double-length keys 
behave like single-length keys only when both halves of the double-length key 
are identical. Control vectors for double-length keys are asymmetric. Any 
double-length key that is exclusive ORed with a control vector will not result in 
a key with identical halves. This double-length key will not behave like a single 
length key. 


You can choose one of two methods for migrating the keys. 
Method 1 (Recommended) 


This method provides some solutions to the considerations listed above and is the 
recommended method to use. 


To migrate the cross-domain keys from Cryptographic Support to CCA, you will 
need to use a key-encrypting key that is common to both. You can use the 
Cryptographic Support host master key as the common key between 
Cryptographic Support and CCA (in CCA, the host master key is known as the 
master key). Import the Cryptographic Support host master key clear value into 
CCA as an IMPORTER key-encrypting key. Because you enter the host master key 
in two separate parts, you should consider importing it into CCA as two parts 
using the Key_Part_Import (CSNBKPI) CCA API. If you had dual responsibility for 
the Cryptographic Support host master key, you should maintain this dual 
responsibility for this key-encrypting key. Alternatively, if you know both parts of 
the host master key, you could also perform an exclusive OR of the two parts and 
import the key in just one part. The program example uses this method of 
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importing the host master key. You may want to consider importing the host 
master key in a completely separate process instead of combining it with the 
migration of all cross-domain keys like the program example does. 


There are three types of cross-domain keys: 
* Receiving cross-domain keys 

* Sending cross-domain keys 

* PIN cross-domain keys 


The CCA equivalent of receiving cross-domain keys are IMPORTER key-encrypting 
keys. Both are used for receiving or importing an encrypted key. 


Sending-cross-domain keys are used for both a) encrypting data keys, which can 
then be sent to another system, and b) translating encrypted personal identification 
numbers (PIN). CCA has stricter key separation than the Cryptographic Support 
product, so you cannot generate or import a key that provides both functions. If 
the key is used as both an EXPORTER key-encrypting key and an OPINENC 
(outbound PIN encrypting) key, you need to import sending-cross-domain keys 
twice into two different keys with two different key types. 


You may use PIN-cross-domain keys for generating PINs and verifying PINs. CCA 
separates these two usage’s into PINGEN (PIN generation) and PINVER (PIN 
verification) keys. If the key is used for both generating and verifying PINs, you 
need to import PIN-cross-domain keys twice as well. 


While the host master key encrypts data keys, different master key variants 
encrypt cross-domain keys. 


* Master key variant 1 encrypts sending cross-domain keys. Variant 1 is the result 
of an exclusive-OR operation of the host master key with 8 bytes of hexadecimal 
88. 


* Master key variant 2 encrypts receiving cross-domain keys. Variant 2 is the 
result of an exclusive-OR operation of the host master key and 8 bytes of 
hexadecimal 22. 


* Master key variant 3 encrypts PIN cross-domain keys. Variant 3 is the result of 
an exclusive-OR operation of the host master key and 8 bytes of hexadecimal 44. 


Note: If you were to only import the clear key value of the host master key into 
CCA, you would not be able to migrate any keys. You need to factor in which 
master key variant encrypts the key in order to migrate it. 


The 8 byte values for creating master key variants are analogous to control vectors. 
The process of migrating keys can be thought of as changing control vectors on a 
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key. The IBM 4758 CCAIIBM 4758 PCI Cryptographic Coprocessor CCA Basic 
Services Reference and Guide] describes a method for such a process. The 


method is the pre-exclusive-OR technique. If the clear key value of a 
key-encrypting key (the host master key in this case) is exclusive-ORed with 
control vector information before importing the key, you can effectively change the 
control vector for any key that this key-encrypting key imports. 


The pre-exclusive-OR technique works well if you are working with single-length 
keys. For double-length keys, the technique must be changed because the control 
vector for the right half of a CCA key is different than the control vector for the 
left half. To overcome this difference, import the key twice, as follows: 
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1. Create a 16 byte value such that each 8 byte half is identical to the left half of 
the control vector of the key you want to import. Use this 16 byte value in the 
pre-exclusive-OR technique to create an importer key-encrypting key that you 
can refer to as the "left-importer.” Only the left half of keys that are imported 
using this key-encrypting key will be valid. 

2. Create another 16 byte value such that each 8 byte half is identical to the right 
half of the control vector of the key you want to import. Use this 16 byte value 
in the pre-exclusive-OR technique to create an importer key-encrypting key. 
Using this importer key-encrypting key, only the right half of the keys that are 
imported will be valid 


3. Import the cross-domain twice: 


a. First use the key-encrypting key created in step 1 and save the left half of 
the result. 


b. Then use the key-encrypting key created in step 2 and save the right half of 
the result. 


4. In the final step, concatenate the left half of the result from step A with the 
right half of the result from step B. Place the combined results in a new key 
token. 


You now have a CCA double-length key that behaves like the cross-domain key 
from the Cryptographic Support for iSeries product. 


“Using IMPORTER key-encrypting keys” on page 125)summarizes all of the 


importer key-encrypting keys that are needed to import all of the cross-domain 
keys. It also describes how to create the importer key-encrypting keys. 


Method 2 


Note: You should only use this method if you feel comfortable with the security of 
your system and environment. This method is easier than the recommended 
method, but it presents a greater security risk for your cross-domain key 
files, since the cross-domain keys will be in clear form in application 
storage. 

1. Import the host master key into CCA as a data key by using the 
Clear_Key_Import (CSNBCKI) CCA API. Remember to perform an exclusive 
OR operation on the key with the values needed to produce data keys 
equivalent to the master key variants as follows: 

* Master key variant 1 encrypts sending cross-domain keys. Variant 1 is the 
result of an exclusive-OR operation of the host master key with 8 bytes of 
hexadecimal 88. 

* Master key variant 2 encrypts receiving cross-domain keys. Variant 2 is the 
result of an exclusive-OR operation of the host master key and 8 bytes of 
hexadecimal 22. 

* Master key variant 3 encrypts PIN cross-domain keys. Variant 3 is the result 
of an exclusive-OR operation of the host master key and 8 bytes of 
hexadecimal 44. 


You will have 3 different data keys after this step. 


2. Use the Decrypt (CSNBDEC) CCA API to decrypt the cross-domain keys to 
return the clear key values. Use the correct data key to decrypt it. 


3. Use the Key_Part_Import (CSNBKPI) CCA API to import the clear key into 
CCA. 
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You should not consider this method to be secure. All of the keys will have been in 
clear form in application storage at some time during this method. 


Congratulations! You are now qualified to write a program to migrate 
cross-domain keys or you can change the following program example. 


Example: Migrating cross-domain keys into your 4758 Coprocessor, to migrate 


cryptographic support cross-domain keys: Change this program example to suit 
your needs for migrating Cryptographic Support for iSeries cross-domain key files 
into your 4758 Coprocessor. 


[BRK RK ERA KERR K ERK KEKE KKK EKA KKE KKK IKK KKK EKA K KIKI KEKE AKER | 
/* This program migrates keys stored in the file QACRKTBL in library */ 
/* QUSRSYS to key storage for Option 35 - CCA Cryptographic Service 
/* Provider. The QACRKTBL file contains cross domain keys that are 
/* used for the Cryptographic Support licensed program, 5769-CR1. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 


of 


these program. All programs contained herein are 


provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


The 


Bw 
1 


keys are migrated by the following steps: 


The master key used for 5769-CR1 passed as a parameter. 
Build importer keys using the master key, 8 bytes of a mask 
to create a variant, and a control vector. 

The file QACRKTBL is opened for input. 

A record is read. 

Import the key using the pre-exclusive OR process. CCA uses 


*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


control vectors while non-CCA implementations don't. 5769-CR1x/ 


creates master key variants similar to what 4700 finance 
controllers do. Since the control vector and master key 
variant material affect how the key is enciphered, the pre- 
exclusive OR process "fixes" the importer key so that it can 
correctly import a key. 


*SND keys are imported twice as an EXPORTER and OPINENC keys. 


*PIN keys are imported twice as a PINGEN and IPINENC keys. 
*RCV keys are imported as a IMPORTER key. 


6- A key record is created with a similar name as in QACRKTBL. 


7 = 


8 - 


For key names longer than 8 characters, a '.' will be 
inserted between the 8th and 9th characters. Also a 1 byte 
extension is appended that describes the key type. 


For example, MYKEY *RCV ---->  MYKEY.R 
MYKEKQ0001 *RCV ----> MYKEKOQ00.01.R 
For «SND and *PIN keys, a second key record is also created. 
For example, MYKEY *SND ---->  MYKEY.S 
MYKEY.0 
MYPINKEY «PIN ----> MYPINKEY.P 
MYPINKEY.1 


The key is written out to key store. 


Steps 4 through 7 are repeated until all keys have been 
migrated. 
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*/ 
*/ 
*/ 
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*/ 
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*/ 
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/* */ 


/* x*/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* */ 
/* Parameters: x/ 
/* nonCCA master key - 8 bytes */ 
/* x*/ 
/* Example: */ 
/* CALL PGM(MIGRATECR) PARM(X'1C23456789ABCDEF' ) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to be used is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* */ 
/* x*/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(MIGRATECR) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(MIGRATECR) MODULE (MIGRATECR) */ 
/* BNDSRVPGM(QCCA/CSNBKIM QCCA/CSNBKPI QCCA/CSNBKRC */ 
/* QCCA/CSNBDEC QCCA/CSNBKRW) */ 
/* */ 
/* Note: Authority to the CSNBKIM, CSNBKPI, CSNBKRC, and CSNBKRW */ 
/* service programs in library QCCA is assumed. x/ 
/* x*/ 
/* x*/ 
/* The Common Cryptographic Architecture (CCA) verbs used are: x/ 
/* x*/ 
/* Key Import (CSNBKIM) x/ 
/* Key Part_Import (CSNBKPI) */ 
/* Key Record Create (CSNBKRC) */ 
/* Key Record Write (CSNBKRW) */ 
/* x/ 
/* x/ 


[RRR R KKK KK EAK KER AKER AKER KAKA KEIRA KEK AKI KKK AK KEK AREA KER | 


[RRR RK KERR KEK KKK K KEK AKER KKK AK KEK KK EAR KKK KKK KKK KAKA KKK KEE KKK | 


/* Retrieve various structures/utilities that are used in program. */ 
[BRK R KKK KEKE AK KERR KER IKE KKK AK KEK KEIRA KEK IKEA IKEA KEK KEE KARE | 


#include <stdio.h> /* Standard I/0 header. */ 
#include <stdlib.h> /* General utilities. x/ 
#include <stddef.h> /* Standard definitions. x/ 
#include <string.h> /* String handling utilities. x/ 
#include "miptrnam.h" /* MI templates for pointer */ 

/* resolution instructions. x*/ 
#include "csucincl.h" /* Header file for security API */ 


[KERR KKK KK EAR KERR KKK KKK KKK KKK KAKA KKK AK KEK KKK KAKA KEKE KKK | 
/* Declare function prototype to build tokens to import keys x/ 
[RRR KKK KK ERK KEI KKK KKK KKK KAKA KKK KKK AK KEK KKK KKK AK KEK AREA KEE | 
int buildImporter(char * token, 


char * clearkey, 
char * preXORcv, 
char * variant); 


[BERR KERR KEKE AK KER KKK AKER KK AK KEK KEIRA KEK IKEA IKEA AKER AKER AKER | 


/* Declare function prototype to import a non-CCA key and put it */ 
/* into key store. */ 
[RRR RK KER KK EK KK KAR KEKE KKK KKK AK KAKA KEK KK KIARA KKK KEE KARE KE | 
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int importNonCCA(char * label, 
char * left_importer, 
char * right_importer, 
char * cv, 
char * encrypted_key); 


[RRR KE RAK KEIR KERR KEK EKER AK KEK KRABI KKK KKK IKKE AK KEK AKER | 


/* Declares for working with files x/ 
[RRR RK KKK KEI KKK KKK KK KKK KKK KKK AK KAKI KK KIKI EA KKK AREA KEKE | 
#include <xxfdbk.h> /* Feedback area structures. x/ 
#include <recio.h> /* Record 1/0 routines */ 
_RFILE xdbfptr; /* Pointer to database file. */ 
_RIOFB_T *db_fdbk; /* 1/0 Feedback - data base file */ 
_XXOPFB_T xdb_opfb; 


[BRK RK ERA KK ERK KERR KEKE KEIR KEK AK KEI KEIRA KKK KKK IKKE IKKE KARE AKER | 
/* Define the record for cross domain key file QACRKTBL */ 
[BRK RK ERA KEKE AK KEK KK EKA KEK KEK AK KEK KK AKKEK KKK KK EKA IKEA KKK AREA KER | 
struct 

{ 

char  label[10]; 

char _key_type; 

char __key_value[8]; 

} key_rec; 


[BERR K ERK KK ERK KEIR K EKA K EKER AK KEK AKIRA KEK KKK AK KEK KKK A KEKE | 
/* Define the structure for key tokens */ 
[ REK RK KKK K EA KKK AK KEK KKK KKK KK KKK IK KAKI KKK A KKK KEE A KEK KK | 


typedef struct 


char __ tokenType; 

char reserved1; 

char MasterKeyVerifPattern[2] ; 
char version; 

char reserved2; 

char flagBytel; 

char flagByte2; 

char __reserved3[8]; 

char leftHalfKey[8]; 

char rightHalfKey[8]; 

char  controlVectorBase[8] ; 
char rightControlVector[8]; 
char reserved4[12]; 

char tvv[4]; 

} key_token_T; 


[RRR RK ERR KK ERK KEK KKK AK KKK KKK KKK KKK KKK AKKK AK KAKA AKER AKER | 


/* Declare control vectors used for building keys */ 
[RRR K ERA KK ERK KEK KK EAR KEK KK EKA A KKK AKER AKER KER | 
char pingen_cv[16] = { 0x00, 0x22, Ox7E, 0x00, 


0x03, 0x41, 0x00, 0x00, 
0x00, 0x22, Ox7E, 0x00, 
Qx03, 0x21, 0x00, 0x00}; 


{ 0x00, 0x21, Ox5F, 0x00, 
0x03, 0x41, 0x00, Ox00, 
0x00, 0x21, Ox5F, 0x00, 
0x03, 0x21, 0x00, 0x00}; 


char ipinenc_cv[16] 


0x00, 0x24, Ox77, Ox00, 
0x03, 0x41, 0x00, 0x00, 
0x00, 0x24, 0x77, 0x00, 
0x03, 0x21, 0x00, 0x00}; 


iT} 
— 


char opinenc_cv[16] 


char importer_cv[16] = { 0x00, 0x42, Ox7D, 0x00, 
0x03, 0x41, 0x00, 0x00, 
0x00, 0x42, Ox7D, 0x00, 
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Qx03, Ox21, 0x00, 0x00}; 


char exporter_cv[16] = { 0x00, 0x41, 0x7D, 0x00, 
0x03, 0x41, 0x00, 0x00, 
0x00, 0x41, Ox7D, 0x00, 
0x03, 0x21, 0x00, 0x00}; 


char importer_cv_part[16] = { 0x00, 0x42, Ox7D, 0x00, 
0x03, 0x48, 0x00, 0x00, 
0x00, 0x42, Ox7D, 0x00, 
0x03, 0x28, 0x00, 0x00}; 


char exporter_cv_part[16] = { 0x00, 0x41, 0x7D, 0x00, 
0x03, 0x48, 0x00, 0x00, 
0x00, 0x41, Ox7D, 0x00, 
0x03, 0x28, 0x00, 0x00}; 


[RRR RKKRAKK EAR KERR KEK AKER KKK A KKK KK EAR KEKKKEK IKEA AKA KKE KAKA AKER | 


/* Start of mainline code. 


*/ 


[KEK RK KER KK ERK KEK KKK AKER KKK AK KEK KKK KKK KEK KKK KKK AK KEK AREA KEKE | 


int main(int argc, char *argv[]) 


{ 


long i,gj.ks /* Indexes for loops 
char key_label [64]; /* label of new key 
char key_label1[64]; /* label of new key 


[BRK R KKK KEKE AK KER KKK AKER KKK IKEA KK EA KK AKKEA AREA EK EKER KER | 


/* Declare importer keys - two keys are needed for each type */ 
[BRK RK KERR KK ER KKK K KEK KKK KKK KKK IK KK EAE K KAKA AKER AKER KEE | 


char EXPORTER_importerL[64] ; 
char EXPORTER_importerR[64] ; 
char OPINENC_importerL[64] ; 
char OPINENC_importerR[64] ; 
char IMPORTER_importerL[64] ; 
char IMPORTER_importerR[64] ; 
char PINGEN_importerL[64] ; 

char PINGEN_importerR[64] ; 

char IPINENC_importerL[64] ; 
char IPINENC_importerR[64] ; 


[RK RK KER KK ERK KKK KEK KKK KKK IKK KK KEIR KAA KEK KKK KKK KAKA KERKKER KK | 


/* Declare variables to hold bit strings to generate master key */ 
/* variants. */ 
[KEK AK KER KEKE AK KER AKER ARE KK KEK A KKK KK EAR KIEK KKK AREA KKK A AKER AKER | 
char variant1[16]; 
char variant2[16]; 
char variant3[16]; 


*/ 
*/ 
*/ 


[RRR KKK KEKE AK KERR KEK AKER KKK AK KAKA KKK AKAIKE IKKE AKER AEE KA KER | 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Build the key tokens for each of the importer keys using 


Key_Token Build. Each key is built by using a variant, a control 
vector, and the clear key. Master key variant 1 is the result of 


an exlusive OR of the master key with hex '8888888888888888' , 
Master key variant 2 is the result of an exclusive OR of the 
master key with hex '2222222222222222', and Master key varient 3 
is the result of an exclusive OR of the master key with hex 
"A444agggggaggaga', During the import operation, the control 
vector is exclusive OR'ed with the importer key. The effect of 


the control vector is overcome by including the control vector as 


key part. Then when the import operation is done, the exclusive 
OR operation will result in the original key. For double keys, 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


the left and right half of the control vector is not the same and */ 
therefore, XORing with the control vector will not result in the */ 
original key - only one half of it will be valid. So two keys are*/ 


needed - one for each half. 


*/ 


[BRK RKRK ERK ERK KER KKK KKK KK KA KKK KK EAR KEK KKK IKKE AK KEK AKER AKER KK | 
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memset (variantl, 0x88, 16); 
memset(variant2, 0x22, 16); 
memset (variant3, 0x44, 16); 


if (buildImporter(EXPORTER_importerL, argv[1], 
exporter_cv, variantl) || 


buildImporter(EXPORTER_importerR, argv[1], 
&exporter_cv[8], variantl) || 


buildImporter(IMPORTER_importerL, argv[1], 
importer_cv, variant2) | 


buildImporter(IMPORTER_importerR, argv[1], 
&importer_cv[8], variant2) || 


buildImporter(PINGEN importerL, argv[1], 
pingen_cv, variant3) || 


buildImporter(PINGEN _importerR, argv[1], 
&pingen_cv[8], variant3) || 


buildImporter(IPINENC_importerL, argv[1], 
ipinenc_cv, variant3) || 


buildImporter(IPINENC_importerR, argv[1], 
&ipinenc_cv[8], variant3) || 


buildImporter(OPINENC_importerL, argv[1], 
opinenc_cv, variant1) || 


buildImporter(OPINENC_importerR, argv[1], 
&opinenc_cv[8], variant1)) 


printf("An error occured creating the importer keys\n"); 
returns; 
[BRK RK ERA KK ERK REAR KEK AKER KERIKERI KAKA KKK KKK KIRA KKK AKER AREA | 
/* Open database file. */ 


[RRR RK KKK KEIR RRA K KKK KKK KKK AK KEK KK IK KAKI KKK AKIRA KKK AKER AKER KK | 


/* Open the input file. */ 

/* If the file pointer, */ 

/* dbfptr is not NULL, */ 

/* then the file was */ 

/* successfully opened. */ 
if (( dbfptr = _Ropen("QUSRSYS/QACRKTBL", "rr riofb=n")) 


= NULL) 
db_opfb = _Ropnfbk( dbfptr ); /* Get pointer to the */ 
/* File open feedback */ 
/* area. */ 
j = db_opfb->num_records; /* Save number of records*/ 


[KEK KKK KAR KEIR KKK KER KK KI KKK AKER KEIR KKK KEKE KKK KAA A AKER KEKE | 
/* Read keys and migrate to key storage. x/ 
[RRR ARK KA KK AK KEI KKK AKER KKK KAKA KEI KK EA KK KAA K EI KKEKAKKEK AKER ERE | 
for (i=1; i<=j; i++) /* Repeat for each record */ 
/* Read a record */ 
db_fdbk = Rreadn(dbfptr, &key_rec, 
sizeof(key_rec), __DFT); 
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[BRK I KKK KK KIRK ER A KKK KKK KKK KKK KKK A KEK KK ERA | 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Generate a key label for the imported keys. */ 
The key label will be similar to the label that was used for */ 
the QACRKTBL file. If the label is longer than 8 characters, */ 
then a period '.' will be inserted at position 8 to make it */ 
conform to label naming conventions for CCA. Also one x/ 
one character will be added to the end to indicate what type */ 
of key. 5769-CR1 does not require unique key names across all*/ 
key types. CCA requires unique labels for all keys. x/ 


[BRK R KKK KK KIRK R KKK KK KKK KKK AKA KEIRA KKK AKER KKK AKER KKK ER KKK | 


memset ((char *)key_label,' ',64);  /* Initialize key label ~*/ 
/* to all blanks. x/ 


/* Copy first bytes of label x/ 
memcpy((char *)key_label, (char *)key_rec.label,8); 


/* If label is longer than 8 characters, add a second element*/ 
if (key_rec.label[8] != ' ') 


key_label [8] ‘eS 

key_label[9] = key_rec.1abel [8]; 
key_label[10] = key_rec.label[9]; 
} 


/* *SND keys and *PIN keys need to be imported twice so */ 
/* make a second label x/ 
if (key_rec.key type != 'R') 

memcpy((char *)key_labell, (char *)key_label,64); 


/* Add keytype to label name. Search until a space is found ~/ 
/* and if less than 8, add the 1 character keytype. If it */ 
/* is greater than 8, add a second element with the keytype */ 


/* 'R' is *RCV key, 'S' is *SND key, 'P' is *PIN key, */ 
/* 'I' is an IPINENC key and '0' is OPINENC key */ 
for (k=1; k<=11; k++) 
{ 
if (key_label[k] == ' ') 
{ 
if (k != 8) 
{ 


key_label[k] = key_rec.key_type; 


/* If this is a *SND or «PIN key, update the keytype ~*/ 
/* in the second label as well */ 
if (key_rec.key_ type != 'R') 


memcpy((char *)key_labell, (char *)key_label,64); 
if (key_rec.key_type == 'S') 
key_labell[k] = '0'; 
else 
key_label1[k] = 'I'; 
} 


} 


else 


key_label [8] 
key_label [9] 


key_rec.key_type; 


/* If this is a *SND or «PIN key, update the keytype ~«/ 
/* in the second label as well */ 
if (key_rec.key_type != 'R') 


memcpy((char *)key_labell, (char *)key_label,64); 
if (key_rec.key_type == 'S') 

key_label1[9] = '0'; 
else 

key_label1[9] = 'I'; 


iSeries: Cryptographic hardware 


[BERR KK RAKK RAK KEA KK ERK K ERK KEK IKEA KEIR K EA KKK AKER KKK ER EKER | 


/* Check for the type of key that was in the QACRKTBL file */ 
/* - S for SENDER key will become two keys - EXPORTER and OPINENC*/ 
/* - R for RECEIVER key will become IMPORTER key */ 
/* - P for PIN will become two keys - PINGEN and IPINENC */ 
/* Set the key id to the key token that contains the key under */ 
/* which the key in QACRKTBL is enciphered. */ 


/* Set the key_type SAPI parameter for the Secure _Key_Import verb*/ 
[BRK RK KEK KKE AK KER KK ERIK ERK KEIRA KK EAR KEKKKE A A KEK KE KAKA AKER ERE | 
if (key_rec.key_type == 'S') 
{ 
/* Import the exporter key */ 
if (importNonCCA(key_label, 
EXPORTER_importerL, 
EXPORTER_importerrR, 
exporter_cv, 
key_rec.key_value) ) 
{ 
printf("An error occured importing an exporter key\n"); 
break; 


} 


/* Import the OPINENC key x/ 
if (importNonCCA(key_labell, 
OPINENC_importerL, 
OPINENC_importerR, 
opinenc_cv, 
key_rec.key_value)) 
{ 


printf("An error occured importing an opinenc key\n"); 


break; 
} 
} 
else 
if (key_rec.key_type == 'R') 
{ 
/* Import the importer key x*/ 


if (importNonCCA(key_label, 
IMPORTER_importerL, 
IMPORTER_importerR, 
importer_cv, 
key_rec.key_value) ) 
{ 
printf("An error occured importing an importer key\n"); 
break; 


} 


else 
{ 
/* Import the PINGEN key x/ 
if (importNonCCA(key_label, 
PINGEN_importerL, 
PINGEN_importerR, 
pingen_cv, 
key_rec.key_value) ) 
{ 
printf("An error occured importing a PINGEN key\n"); 
break; 


} 
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[ee 


/* C 


[ «ee 


} 


el 


[*** 
/* 
/* 
/* 
/* 
/* 
[ek 
int 


{ 

[ek 
/* D 
[*ee 
char 
long 
long 
long 
long 
char 
char 
char 
char 
key_ 


[xk 
/* B 


[*** 


/* Import the IPINENC key */ 
if (importNonCCA(key_labell, 
IPINENC_importerL, 
IPINENC_importerR, 
ipinenc_cv, 
key_rec.key_value) ) 
{ 
printf("An error occured importing an ipinenc key\n"); 
break; 


} 


} /* End loop repeating for each record */ 


KR KKK A KKK AK KKK KKK KKK KKK IK KEK KKK A KEI KKK IKKE AK KEK AKER AREA KER KE | 


lose database file. x/ 
KR KKK A KKK AK KKK K KKK KK KKK KIRKE KKK IKEA AK KIA KEK KKK AREA KER | 


if (dbfptr != NULL) /* Close the file. */ 
_Rclose(dbfptr) ; 


/* End if file open leg */ 


se 
printf("An error occured openning the QACRKTBL file.\n"); 
/* End of main() */ 
KR KKK A KKK AK KKK K KARR KEKE IK KEK KKK IKEA KKK IKK K KEK KK EKA AKER KK | 


buildImporter creates an importer token from a clearkey exclusivex/ 
OR'ed with a variant and a control vector. The control vector */ 
is XOR'ed in order to import non-CCA keys. The variant is XOR'ed*/ 
in order to import from implementations that use different */ 
master key variants to protect keys as does 5769-CR1. */ 
KR KKK A KKK AK KKK KKK KKK KEIR KEK KKK AKER A KEI KK EKA AKER | 
buildImporter(char * token, 

char * clearkey, 

char * preXORcv, 

char * variant) 


KR KKK A KKK KK KKK KKK KKK KKK KKK AKER KE | 


eclare variables used by the SAPI's «/ 
HAKKAR KKK KKK KKK KKK KEK AKER KER AER | 
rule_array[16]; 
rule_array_count; 
return_code; 
reason_code; 
exit_data_length; 
exit_data[4]; 
keyvalue[16]; 
keytype[8] ; 


ctl_vector[16]; 

token_T *xtoken_ptr; 

KR KKK AK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KREKK KE | 

uild an IMPORTER token */ 

KR KKK A KKK AK KKK KKK KKK KKK IK KER AK KE AKER AKER | 

memset(token, 0, 64); /* Initialize token to all 0's */ 

token_ptr = (key_token_T *) token; 

token_ptr->tokenType = 0x01; /* 01 is internal token x*/ 

token_ptr->version = 0x03; /* Version 3 token x/ 

token_ptr->flagBytel = 0x40; /* High order bit is @ so key */ 
/* is not present. The 40 */ 


/* bit means that CV is presentx/ 
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/* Copy control vector into */ 
/* the token. */ 
memcpy (token_ptr->controlVectorBase, importer_cv_part, 16); 
/* Copy TVV into token. This */ 
/* was calculated manually by */ 
/* setting all the fields and */ 
/* then adding each 4 bytes of */ 
/* the token (excluding the */ 


/* TVV) together. */ 
memcpy (token_ptr->tvv,"\xOA\xF5\x3A\x00", 4); 


[BRK K ERA KRK EA KKK KK EAR RAK KEKE KEI KKK AKER AKER IKKE IKEA AKER EKER EKER | 
/* Import the control vector as a key part using Key _Part_Import */ 
[RRR KKK KK A KKK KKK K KKK KEK KK KIRK KAKA KKK KK KKK KEK KK EKA KEKE KE | 
exit_data_length = 0; 
rule_array_count = 1; 
memcpy(ctl_vector, preXORcv, 8); 
memcpy (&ctl_vector[8], preXORcv, 8); /* Need to copy the 
control vector into the 
second 8 bytes as well*/ 
memcpy(rule_array, "FIRST ", 8); 
CSNBKPI( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(char *) ctl_vector, 
(char *) token); 


if (return_code > 4) 
{ 
printf("Key_Part_Import failed with return/reason codes \ 
%d/%d \n",return_code, reason_code); 
return 1; 


} 


[KERR KEK KK AK KEIR KEIR K KKK KEK AKER KKK AKER IKK A KKK IKEA AKER KE | 
/* Import the variant as a key part using Key_Part_Import */ 
[RHR K EKA KEIR RRA K KAKA KKK KKK KKK KKK A KKK IKEA K IKEA K KAA KER KKK | 
memcpy(rule_array, "MIDDLE ", 8); 
CSNBKPI( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(char *) variant, 
(char *) token); 


if (return_code > 4) 
{ 
printf("Key_Part_Import failed with return/reason codes \ 
%d/%d \n",return_code, reason_code); 
return 1; 


} 


[BRK RK EAR ERK KER KK EAR KARR K EKER KKK A KEK IKKE IKEA AKER EKER KE | 
/* Import the clear key as a key part using Key Part_Import */ 
[RRR RK ERK KK EAR RRA K KEK KKK KK EAR KKK KKK A KKK AK KIA KKK KK EKA KEKE KE | 
memcpy(keyvalue, clearkey, 8); 
memcpy (&keyvalue[8], clearkey, 8); /* Make key double length«/ 
memcpy(rule_array, "LAST ny 8)3 
CSNBKPI( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(char *) keyvalue, 
(char *) token); 
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ret 


} 


[BRK RK KER KEKE AK KERR KEK K KEK KKK AKER AK KEI KK AKK IKK AK KEK AKER A AERA KKERKE | 


/* importNonCCA imports a double length key into CCA from the 


/* n 


if (return_code > 4) 


{ 


printf("Key_Part_Import failed with return/reason codes \ 
sd/%d \n",return_code, reason_code) ; 


return 1; 


} 


urn 0; 


on-CCA implementation 


int importNonCCA(char * label, 
char * left_importer, 
char * right_importer, 
char * cv, 
char * encrypted_key) 
en eee eee ee 
/* Declare vaiables used by the SAPIs */ 
[KEK RK KKK KK RAK KEK KK AK KKK KKK KER KKK AK ERK | 
long return_code, reason_code; 
char exit_data[4]; 
long exit_data_length; 
long rule_array_count; 
char rule_array[24]; 
char keytoken[64]; 
char external key [64]; 
char keyvalue[16] ; 
char keytype[8] ; 
char *importer; 
char mkvp[2]; 
key_token_T *token_ptr; 
int tvv, tvv_part; 
char *tVV_pOS3 


[BRK RK KER KEKE RK KER AKER AKER K KKK A KEK KEKE K KERR | 


/* Build an external key token to IMPORT from */ 


[BRK RK KKK KK EKA KEK AKER AKER KKK KIRKE KKK ERK ER KKK | 


memset ((void *)externalkey,'\00',64); 
token_ptr = (key_token_T *)externalkey; 


token_ptr->tokenType = 0x02; /* 02 is external token 
token_ptr->version = 0x00; /* Version 0 token 
token_ptr->flagBytel = OxC0; /* High order bit is 1 so 


/* key is present. The 
/* 40 bit means that CV 
/* is present 


memcpy (token_ptr->controlVectorBase, cv, 16); /* Copy control 
vector into token 


memcpy (token_ptr->leftHalfkey,encrypted_key, 8); 


memcpy (token_ptr->rightHalfKey,encrypted_key, 8); 


[ REKRK RRA KRK ERK RRA K KEI KKK IKEA KKK EKER KERR | 
/* Calculate the TVV by adding every 4 bytes */ 
[BRK K RRA K KEK K KEK KKK AK KKK KEK KK EAA KEK KERR | 
tvv_pos = externalkey; 
tvv = 0; 
while (tvv_pos < (externalkey + 60)) 
{ 
memcpy ((void*)&tvv_part,tvv_pos,4); 
tvv += tvv_part; 
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/* Copy key 
into left half 
/* Copy key 
into right half 


*/ 
*/ 


[RRR RK RRR KK EIR KER KKK KKK KKK KKK KKK EA KK IKK EK KKK AK KKK AK KAKA KKK KK | 


tvv_pos += 4; 
} 
memcpy(token_ptr->tvv, (void*)&tvv, 4); 


[BERR KKK KK EAR KEK KKK AK KAR KEK KK KKK KER A KKK AK EKA K KEK KK ERK ERK | 
/* Import the left half of the key using Key_Import and */ 
/* the importer built with left half of the control vector */ 
[ REK RK ERR KK EAR RRA K KAKA KKK KKK IK KER A KKK IKKE AK KEK AKER AKER KK | 
exit_data_length = 0; 
memcpy(keytype, "TOKEN ", 8); 
memset ((void *)keytoken, '\00',64); 
CSNBKIM( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(char *) keytype, 
(char *) externalkey, 
(char *) left_importer, 
(char *) keytoken) ; 


if (return_code > 4) 
{ 
printf("Key_ Import failed with return/reason codes \ 
%d/%d \n",return_code, reason_code) ; 
return 1; 


} 


[BRK RK ERA KK ER KKK KK EAE EKA K KEK KK EKER EKER | 
/* Save left half of key out of key token */ 


[KEK RK KKK KK EAR RRA K REAR KKK KKK EKER AKER EKER | 


memcpy(keyvalue, &keytoken[16], 8); 


[BRK RK KKK KK RAK KKK KKK AK KKK KKK KK KKK KER AK KAKA KKK AKER AKER EK | 
/* Import the right half of the key using Key_Import and */ 
/* the importer built with right half of the control vector*/ 
[BERR KERR KERR KEK KK RAKE KK KEK AKER AKER IKKE IKEA AREA AKER AKER EK | 
memcpy(keytype, "TOKEN ", 8); 
memset ((void *)keytoken, '\00',64); 
CSNBKIM( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(char *) keytype, 
(char *) externalkey, 
(char *) right_importer, 
(char *) keytoken) ; 


if (return_code > 4) 
{ 
printf("Key_Import failed with return/reason codes \ 
%d/%d \n",return_code, reason_code); 
return 1; 


} 


[KERR KER AK K EA KK EAR KEK KKK KK EKER ERA KER AK KERKE | 


/* Save right half of key out of key token */ 


[KEK RK ERK KK RAK RRA K KEIRA KK EK KK EKA ERA KKK | 


memcpy (&keyvalue[8], &keytoken[24], 8); 


[BRK RK ERA KK AK KERR KEIR KKK KEK EKER A KERIKERI KEIRA KKK KEK AKER AKER ARK | 


/* Get master key verification pattern from the last key token built */ 
[RRR K KKK KEK K KAR KAKA KKK KKK KER KKK A KKK IK KAKA KKK KER AKER KKK | 


mkvp[0] = keytoken[2]; 
mkvp[1] = keytoken[3]; 


[KEK RK RRR KK EA K RRA KK AK KKK KAKI KIRA KK ERA KEKE AKER KK ERK | 
/* Build an internal key token using both key halves just */ 
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/* imported and using the master key verification pattern */ 
[BRK KKK RR KEKE AK KEIRA K KKK KEK KK EAI AKER IKKE KEKE AKER | 
memset ((void *)keytoken, '\00',64); 
exit_data_length = 0; 
token_ptr = (key_token_T *)keytoken; 
token_ptr->tokenType = 0x01; 


token_ptr->version 


= 0x03; 


token_ptr->flagBytel = OxC0; 


token_ptr->MasterKeyVeri fPattern [0] 


token_ptr->MasterKeyVeri fPattern[1] 


/* 01 is internal token 

/* Version 3 token 

/* High order bit is 1 so 
/* key is present. The 

/* 40 bit means that CV is 
/* present 


/* Set the first byte of 
/* Master key verification 
/* pattern. 

mkvp LO]; 
/* Set the second byte of 
/* Master key verification 
/* pattern. 

mkvp[1] 5 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


/* Copy control vector into*/ 


/* token 


memcpy (token_ptr->controlVectorBase, cv, 16); 
memcpy (token_ptr->leftHalfKey, keyvalue, 16); /*Copy key to token «/ 


[ BRK KR RAK KEIR RRA K KEIR KEK K EAA KEK EKER KKEKRKRERK | 


/* Calculate the TVV by adding every 4 bytes */ 


[BRK RK RRA K KEK K KEK KKK KKK KIRK K EK KKK KERR ER | 
tvv_pos = externalkey; 


tvv = 0; 


while (tvv_pos < (externalkey + 60)) 


memcpy ((void*)&tvv_part,tvv_pos,4); 
tvv += tvv_part; 


tvv_pos += 


4; 


memcpy(token_ptr->tvv, (void*)&tvv, 4); 


[BERR KKK KK ER KK ERK KER AKER A KKK KKER AKER EKER AK | 


/* Create a Key Record in Key Store 
[KEK KKK ERK K RAK KER KKK A KEKE AK KEK AKER KKK KK | 


exit_data_length = 0; 


CSNBKRC( (long 
(long 
(long 
(char 
(char 


*) 
*) 
*) 
*) 
*) 


&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 

label); 


if (return_code > 4) 


*/ 


printf("Key_Record Create failed with return/reason codes \ 


return 1; 


} 


%d/%d \n",return_code, reason_code) ; 


[BRK RK KER KK EAR KER AKER IKEA KEKE A KKK EKER EKER EK | 


/* Write the record out to Key Store 
[KEK RK KERR KEK KKK K KER AKER KKK EA KKEK AKER AKER | 


CSNBKRW( (long 
(long 
(long 
(char 
(char 
(char 
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*) 
*) 
*) 
*) 
*) 
*) 


&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
keytoken, 

label); 


*/ 


*/ 


} 


if (return_code > 4) 


printf("Key_Record Write failed with return/reason codes \ 
sd/%d \n",return_code, reason_code); 
return 1; 


} 


return 0; 


Using IMPORTER key-encrypting keys: To import all types of cross-domain keys 
you will need the following IMPORTER key-encrypting keys: 


1. 


10. 


11. 


12. 


A KEK for importing the left half of exporter keys. 


Create this key using the clear host master key, the left half of an exporter 
key-encrypting key control vector, and 16 bytes of hex 88. 


A KEK for importing the right half of exporter keys 


Create this key using the clear host master key, the right half of an exporter 
key-encrypting key control vector, and 16 bytes of hex 88. 


A KEK for importing the left half of importer keys. 


Create this key using the clear host master key, the left half of an importer 
key-encrypting key control vector, and 16 bytes of hex 22. 


A KEK for importing the right half of importer keys. 


Create this key using the clear host master key, the right half of an importer 
key-encrypting key control vector, and 16 bytes of hex 22. 


A KEK for importing the left half of OPINENC keys. 


Create this key using the clear host master key, the left half of an OPINENC 
key control vector, and 16 bytes of hex 88. 


A KEK for importing the right half of OPINENC keys. 


Create this key using the clear host master key, the right half of an OPINENC 
key control vector, and 16 bytes of hex 88. 


A KEK for importing the left half of IPINENC keys. 


Create this key using the clear host master key, the left half of an IPINENC 
key control vector, and 16 bytes of hex 44. 


A KEK for importing the right half of IPINENC keys. 


Create this key using the clear host master key, the right half of an IPINENC 
key control vector, and 16 bytes of hex 44. 


A KEK for importing the left half of PINGEN keys. 


Create this key using the clear host master key, the left half of a PINGEN key 
control vector, and 16 bytes of hex 44. 


A KEK for importing the right half of PINGEN keys. 


Create this key using the clear host master key, the left half of a PINGEN key 
control vector, and 16 bytes of hex 44. 


A KEK for importing the left half of PINVER keys. 


Create this key using the clear host master key, the left half of a PINVER key 
control vector, and 16 bytes of hex 44. 


A KEK for importing the right half of PINVER keys. 


Create this key using the clear host master key, the left half of a PINVER key 
control vector, and 16 bytes of hex 44. 
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Migrate key store files 


Procedure here..explain the process of migrating key store files from the Common 
Cryptographic Architecture Cryptographic Service Provider for iSeries Services. 
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This section is mainly for OS/400 application use_of the 4758 Coprocessor. If you 
are using multiple Coprocessors with SSL, see |“Manage multiple 4758 
Cryptographic Coprocessors” on page 182}and|“Clone master keys” on page 192 
After you set up your 4758 Coprocessor, you can begin writing programs to make 


use of your 4758 Coprocessor’s cryptographic functions. You can use programs to 
perform these tasks: 


* |Log on or off of the 4758 Cryptographic Coprocessor”|to work with 


role-restricted APIs. 


° |“Query status or request information” on page 137) 
* |Initialize a key store file” on page 142|if you plan to keep records of your DES 


and PKA keys. 


o Fcreste Dis and PCA eye an page 127 and ctseing them tia DES key tore. 
: 
é 


y] 
* |“Clone master keys” on page 192}when using multiple 4758 Coprocessors. 


Note: Many of the pages in this section include one or more program examples. 
Change these programs to suit your specific needs. Some require that you 
change only one or two parameters while others require more extensive 
changes. For security reasons, IBM recommends that you individualize these 
program examples rather than using the default values provided. 


Log on or off of the 4758 Cryptographic Coprocessor 


Logging on 


You need to log on only if you wish to use an API that uses an access control point 
that is not enabled in the default role. Log on with a profile that uses a role that 
has the access control point you want to use enabled. 


After you log on to your 4758 Coprocessor, you can run programs to utilize the 
cryptographic functions for your 4758 Coprocessor. You can log on by writing an 
application that uses the Logon_Control (CSUALCT) API verb. Two example 
programs are provided for your consideration. One of them is written in ILE C, 
while the other is written in ILE RPG. Both perform the same function. 


“Example: ILE C program for logging on to your 4758 Coprocessor” on page 127; 


Logging off 


When you have finished with your 4758 Coprocessor, you should log off of your 
4758 Coprocessor. You can log off by writing an application that uses the 
Logon_Control (CSUALCT) API verb. Two example programs are provided for 
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your consideration. One of them is written in ILE C, while the other is written in 
ILE RPG. Both perform the same function. 


* |“Example: ILE C program for logging off of your 4758 Coprocessor” on page 132 


° |“Example: ILE RPG program for logging off of your 4758 Coprocessor” on 
page 134 


Note: If you choose to use the program examples provided, change them to suit 


Example: ILE C program for logging on to your 4758 


your specific needs. For security reasons, IBM recommends that you 


individualize these program examples rather than using the default values 


provided. 


Coprocessor 


Change this program example to suit your needs for logging on to your 4758 


Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


important legal information. 


Log on to the 4758 card using your profile and passphrase. 


COPYRIGHT 5769-SS1, 5722-SS1 (C) IBM CORP. 1999, 2000 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these program. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 


these programs and files. 


Note: This verb is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 

Parameters: 

none. 
Example: 
CALL PGM(LOGON) 
Note: This program assumes the card with the profile is 


already identified either by defaulting to the CRPO1 
device or by being explicitly named using the 
Cryptographic_Resource_Allocate verb. Also this 
device must be varied on and you must be authorized 
to use this device description. 


Use these commands to compile this program on iSeries: 
ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(LOGON) SRCFILE(SAMPLE) 

CRTPGM PGM(LOGON) MODULE(LOGON) BNDSRVPGM(QCCA/CSUALCT) 


Note: Authority to the CSUALCT service program in the 
QCCA library is assumed. 


The Common Cryptographic Architecture (CCA) verb used is 
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/* Logon_Control (CSUALCT). 
/* 


#include "csucincl.h" /* header file for CCA Cryptographic 


/* Service Provider for iSeries 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 
| HenceeaacasessaseasesesSseess ass sesseeaes ees esse Sseacee cee ssseoses 
/* standard CCA parameters 
| ee ee ee eee ee 
long return_code = 0; 
long reason_code = 0; 
long exit_data_length = 2; 


char exit_data[4]; 
char rule_array[2] [8]; 
long rule_array_count = 2; 


char profile[8]; 

long auth_parm_length; 
char auth_parm[4]; 
long auth_data_length; 
char auth_data[256]; 


/* set rule array keywords 
memcpy(rule_array,"LOGON PPHRASE ", 16); 


/* Check for correct number of parameters 
if (argc < 3) 


{ 
printf("Usage: CALL LOGON ( profile ‘pass phrase')\n"); 
return(ERROR) ; 
} 
/* Set profile and pad out with blanks 
memset(profile, ' ', 8); 


if (strlen(argv[1]) > 8) 
{ 


printf("Profile is limited to 8 characters.\n"); 
return(ERROR) ; 


memcpy(profile, argv[1], strlen(argv[1])); 


/* Authentication parm length must be @ for logon 
auth_parm_length = 0; 


/* Authentication data length is length of the pass-phrase 
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*/ 
*/ 


*/ 


*/ 


auth_data_length = strlen(argv[2]); 


/* invoke verb to log on to the 4758 card x/ 


CSUALCT( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
profile, 
&auth_parm_length, 
auth_parm, 
&auth_data_length, 
argv[2]); 


if (return_code != OK) 

{ 

printf("Log on failed with return/reason codes %1d/%ld\n\n", 
return_code, reason_code); 

} 


else 
printf("Logon was successful\n"); 


Example: ILE RPG program for logging on to your 4758 


Coprocessor 
Change this program example to suit your needs for logging on to your 4758 


Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DAKAR KKKKKKK KER KKK KKK KR KERR KERR RK KR ERE RRR RK RRR RRR RRR RK ER ERR ERR 
D* LOGON 

Dx« 

D* Log on to the 4758 Cryptographic Coprocessor. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

Dx tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx 

Dx Parameters: Profile 

Dx Pass-phrase 

Dx« 

D* Example: 

D* CALL PGM(LOGON) PARM(PROFILE PASSPRHASE) 

Dx 


D* Use these commands to compile this program on iSeries: 
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D* CRTRPGMOD MODULE(LOGON) SRCFILE (SAMPLE) 
D* CRTPGM PGM(LOGON) MODULE (LOGON) 
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Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUALCT service program in the 
Dx QCCA library is assumed. 

Dx« 


Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 


D* This program assumes the card with the profile is 

D* already identified either by defaulting to the CRPO1 
D* device or by being explicitly named using the 

D* Cryptographic_Resource_ Allocate verb. Also this 

D* device must be varied on and you must be authorized 


Dx to use this device description. 


DA RRA KKK KKK KK ERK KK KE KKK KK R RRR KEK KKK RRR RRR KERR KERR RR ER KEK RE RRREKRRRER 


Peeiseeeeeseeee eee ee sesso cee pease see see ese ece Ss 
D* Declare variables for CCA SAPI calls 

DeeaSee Sees rSasoe ste se See SoS aa ee Sea e Sas Seo eee 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

D« «x Exit data length 
DEXITDATALEN S 9B 0 

D* ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Userid parm 

DUSERID S 8 

Dx ** Authentication parameter length 
DAUTHPARMLEN S 9B 0 INZ(0) 

D* ** Authentication parameter 
DAUTHPARM S 10 

D* ** Authentication data length 
DAUTHDATALEN S 9B @ INZ(0) 

Dx ** Authentication data 
DAUTHDATA Ss 50 

Dx« 


DARK RK KARR KKK ERK KK KEK KKK KKK KKK KEK KKK RRR KERR KKK RRR KERR ERK RERREKK 


D* Prototype for Logon Control (CSUALCT) 


DA KRAKKKKKKK KERR KK KEK KK REE KK ERR KKK RRR RRR RRR RRR RRR RER KERR EERE 


DCSUALCT PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DUSR 8 

DATHPRMLEN 9B 0 

DATHPRM 10 

DATHDTALEN 9B 0 

DATHDTA 50 

Dx« 

DA RRRKKKK KKK KEKE KK KEK KKK KERR KEKE KKK RRR R KERR KEK RRR RRR RRR KERR ERRRKRERER 
D* Declares for sending messages to job log 

DARK AK KKK KKK KER KKK KKK KK KKK KKK EK KKK RRR KERR KKK RE RE KR R RRR RRR RK KRERE 


Deeesseee eee Sasseecenee sees ct sst sees eeeee ee eseeee ste seesssese 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Deseeseassescas ses aes cscs sssctsesss esses esses eseseseesscescess 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
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DMSGLENGTH S 9B 0 INZ(75) 


D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFATLRSNC 46 49 

DMESSAGEID Ss 7 INZ(' ') 
DMESSAGEFTLE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER s 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN il 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR KKK KKK KEK KK KEKE KR EKER KER ERK KKK KEKE RR EKER RE KERR RR ER ERK ERERREERE 
Cx START OF PROGRAM * 
C* * 
Cxeseetecceslesccsceesecesss cesses ssesoosesstcSsSescee cesses scesece * 
C *ENTRY PLIST 

C PARM USERID 

C PARM AUTHDATA 

Crees iesessese2s-o2sSeeSo2 Soe Ses seseesa nae a eseeese=>ses5es = * 
Cx Set the keywords in the rule array * 
(kee Hees eee oe ss ee ee ee eee ee ee eee eee eee eet * 
C MOVEL "LOGON =! RULEARRAY 

C MOVE "PPHRASE ! RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 
CxksetsecsasfosccsceeSeeesSssessesesse coe SsteSscseoccesesscoseee * 
Cx Get the length of the passphrase * 
CxsSee eee see see ete se ecbe Sects seen ee ee eee eeele cee ceo ese e ee eee * 
C EVAL AUTHDATALEN = %LEN(%TRIM(AUTHDATA) ) 
Cx« 


CR KKK KK KKK KKK KEKE KKK KEK KER ERK KKK KEKE KR REK ERR ERE RR RR ERE REE ERRERE 


Cx Call Logon Control SAPI 


CR KKK KK KKK KKK KEK KERR EKER KER ERK KK RK EKER KEKE RR ER ERR RRR ERE RR EERE 


C CALLP CSUALCT (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

¢€ RULEARRAYCNT : 
C RULEARRAY : 

C USERID: 

C AUTHPARMLEN: 
¢ AUTHPARM: 

C AUTHDATALEN: 
C AUTHDATA) 
CxeeSSeoseesesasseoseosces * 

Cx Check the return code * 

(¥eeeseesecessseesseesees * 

C RETURNCODE IFGT 0 

Cx Xesesccteescosescossees * 

Cx * Send error message * 

Cx* Se hs a a i a en ct * 

C MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx* 

C ELSE 

Cx« fssaceeseecceeeseeseeos * 

Cx * Send success message * 

Cx 0 ee ee * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ENDIF 
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Cx* 

C SETON LR 
C* 

CR KKK KKK KEK KKK KEKE KKK KER KER ERE RK RK ERE RR ER ERR ER ERE RR EK ERE RK EKER 

Cx Subroutine to send a message 

CR KKK KKK KEK KKK KEKE KKK KEK KKK ERE KK KK EK KEK KKK ERR ER ERK RR EK ERE RK EKER E 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


** 
CSUALCT failed with return/reason codes 9999/9999' 
The request completed successfully 


Example: ILE C program for logging off of your 4758 
Coprocessor 
Change this program example to suit your needs for logging off of your 4758 


Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


ita demeneesneeesseseses sees eee nae os sada csases= oe seesees= ease see ses «/ 
/* Log off the 4758 Cryptographic CoProcessor */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1, 5722-SS1 (C) IBM CORP. 1999, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: This verb is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(LOGOFF) */ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* x/ 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 


#i 
#i 
#i 


Use these commands to compile this program on iSeries: */ 
ADDLIBLE LIB(QCCA) */ 
CRTCMOD MODULE(LOGOFF) SRCFILE(SAMPLE) */ 
CRTPGM PGM(LOGOFF) MODULE(LOGOFF) BNDSRVPGM(QCCA/CSUALCT) x/ 
x/ 
Note: Authority to the CSUALCT service program in the */ 
QCCA library is assumed. */ 
x/ 
The Common Cryptographic Architecture (CCA) verb used is x/ 
Logon Control (CSUALCT). */ 
x/ 
ee a a ae */ 
nclude "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries */ 
nclude <stdio.h> 
nclude <string.h> 
nclude <stdlib.h> 
ee ee a a a a a ae a ee «/ 
standard return codes x*/ 
Be ee cesstestecesscesecsescesoselans esses eceecsescen ccc e ese esescosses */ 


#define ERROR -1 
#define OK 0 


int main(int argc, char *argv[]) 


{ 


long return_code = Q; 

long reason_code = Q; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 1; 


char profile[8]; 
long auth_parm_length; 
char * auth_parm = " "3; 


long auth_data_length = 256; 


char auth_data[300]; 


/* set rule array keywords to log off 


memcpy (rule_array, "LOGOFF 


rule_array_count = 1; 


" 8); 


/* Both Authenication parm and data lengths must be 0 


auth_parm_length 
auth_data_length 


0; 
0; 


/* Invoke verb to log off the 4758 Cryptographic CoProcessor 


CSUALCT( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
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profile, 
&auth_parm_length, 
auth_parm, 
&auth_data_length, 
auth_data); 


if (return_code != OK) 

{ 

printf("Log off failed with return/reason codes %1d/%ld\n\n", 

return_code, reason_code); 

return (ERROR) ; 

} 

else 

{ 

printf("Log off successful\n"); 
return(0K) ; 

} 

} 


Example: ILE RPG program for logging off of your 4758 
Coprocessor 

Change this program example to suit your needs for logging off of your 4758 
Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DAKAR KKK KK KK ERK KEKE KKK KERR KERR RRR RRR ER KERR KER KERR RRR ER KERR ERR EKER 
D* LOGOFF 

Dx« 

Dx Log off from the 4758 Cryptographic Coprocessor. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx 

Dx Example: 

D* CALL PGM(LOGOFF) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(LOGOFF) SRCFILE(SAMPLE) 
D* CRTPGM PGM(LOGOFF) MODULE (LOGOFF) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUALCT service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty_Control (CSUACFC) 

Dx« 

D* This program assumes the card with the profile is 
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Dx already identified either by defaulting to the CRPO1 

D* device or by being explicitly named using the 

D* Cryptographic_Resource Allocate verb. Also this 

D* device must be varied on and you must be authorized 

D* to use this device description. 

DARK AKKKKK KK KER KKK KEK KKK ERK KKK KKK KEKE RK RK E KKK KER KEK RRR RRR RRR RK RERE 


PkeeescsosscsscsecesSsreSssosssssscooosoossssccsssess 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXTTDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT Ss 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Userid parm 

DUSERID S 8 

Dx xx Authentication parameter length 
DAUTHPARMLEN S 9B 0 INZ(0) 

Dx ** Authentication parameter 
DAUTHPARM S 8 

Dx *x Authentication data length 
DAUTHDATALEN Ss 9B 0 INZ(0) 

Dx xx Authentication data 
DAUTHDATA S 8 

Dx« 


DAR RKK KKK KKK KEK KKK EK KKK ERK KEK KKK KEKE RK RRR KEK KR ER KEK RRR KKK ERE 


D* Prototype for Logon Control (CSUALCT) 


DAKAR KKKKK KKK ERK KEKE KKK KERR KKK KERR KERR RRR RRR RR ER KERR ERK ER ERERE 


DCSUALCT PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DUSR 8 

DATHPRMLEN 9B 0 

DATHPRM 8 

DATHDTALEN 9B 0 

DATHDTA 8 

Dxeee seh esea os = -SseS2ooe aac ceases a asa a aaa ae a= ae== = == Se 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

Dkee tee eases aces chee cee eee See eee eee eee eee eee eee eee 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ‘) 
DMSGKEY 5 4 INZ(' ") 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY Ss 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(O) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx 
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CR KKK KKK EK KKK KEKE KR KK EK KKK ERE KKK KER KEK KEKE KKK KER KERR EK ERE RR EKER E 


Cx START OF PROGRAM * 
C* * 
(Fae seee shee esseeeeten ashes sees eee seeseHE ese eee ee eee * 
Cx Set the keywords in the rule array * 
ee ee * 
C MOVEL ‘LOGOFF ! RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

C* 


CR KKK KKK KEK KKK KK EKER EK KKK ERE KK RK ERK REK KERR ER ERK RR EK ERE RR EKER EK 


Cx Call Logon Control SAPI 


CR KKK KKK KEK KKK KEKE KK KK ERK ER ERE RK RK EKER KEK ERR ER ERE RRR ERR RR EKER 


C CALLP CSUALCT (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C USERID: 

C AUTHPARMLEN: 
C AUTHPARM: 

Cc AUTHDATALEN: 
C AUTHDATA) 

Cees eeeee cee seen se cece * 

Cx Check the return code * 

Cieeseeseeesesseeeeeeeees * 

C RETURNCODE IFGT 0 

Cx* tose seeseesessaceaasees * 

Cx * Send error message * 

Cx Kaeo aeeSesassae=eeeoees * 

Cc MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

C* 

C ELSE 

Cx Neos ecweerevecoseeesee * 

Cx * Send success message * 

Cx Fesesesssasesscsscsssse * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx 

C ENDIF 

Cx* 

C SETON LR 
Ce 


CR KKK KKK EK KKK EKER RK KEK KKK ERE KK RK EK KEK KKK KERR KEK ERK RR EK ERE RK EKER E 


Cx Subroutine to send a message 
CR KKK KK KK EK KKK KEKE KK EKER KER ER ERK RK ERE RR ER ERR ER ERE RR EKER RR EKER 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


** 


CSUALCT failed with return/reason codes 9999/9999' 
The request completed successfully 
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Query status or request information 


You can query your 4758 Coprocessor to determine characteristics such as which 
algorithms are enabled, the key lengths it supports, the status of the master key, 


the status of cloning, and the clock setting. The easiest and fastest way to query 


the 4758 Coprocessor is to use the 4758 Cryptographic Coprocessor configuration 
web-based utility. Click on Display configuration and then select a device, then 
select items you want to display. 


If you would prefer to write your own application to query the Coprocessor, you 


can do so by using the Cryptographic_Facility_Query ( 
grams are provided for your consideration.|“Example: Querying the 


prompts the user for the second required keyword. 


The 


IBM 4758 PCI Cryptographic Coprocessor CCA Basic Services Reference and 


describes the Cryptographic_Facility_Query (CSUACFQ) security 


CSUACFO) API verb. Two 


application programming interface, the types of information that you can request, 
and the format of the information that is returned. 


Example: Querying the status of your 4758 Coprocessor 


Change this program example to suit your needs for querying the status of your 
4758 Coprocessor. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Query the 4758 card for status or other information. 
This sample program uses the STATEID and TIMEDATE keywords. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these program. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 

Note: This verb is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 

Parameters: 

none. 
Example: 
CALL PGM(QUERY) 
Note: This program assumes the device to use is 


already identified either by defaulting to the CRPO1 
device or by being explicitly named using the 
Cryptographic_Resource_ Allocate verb. Also this 
device must be varied on and you must be authorized 
to use this device description. 


Use these commands to compile this program on iSeries: 
ADDLIBLE LIB(QCCA) 
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/* CRTCMOD MODULE(QUERY) SRCFILE(SAMPLE) */ 


/* CRTPGM PGM(QUERY) MODULE(QUERY) BNDSRVPGM(QCCA/CSUACFQ) */ 
/* x/ 
/* Note: Authority to the CSUACFQ service program in the */ 
/* QCCA library is assumed. x/ 
/* x*/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Facility_Query (CSUACFQ). */ 
/* x/ 
[ReeeReoaseaasasssesoea Se eee ees aa= seca saes Hae Seo ae eee ees eae ase aoe as */ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 

/* Service Provider for iSeries x/ 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


[Hssataeceetessscsoaseeseassssesssesscs ase sss seeeSessassssoeslessseas: */ 
/* standard return codes x/ 
[#eseSescReee setsese ashes sae -e ede aes ae eee eee oe eet «/ 
#define ERROR -1 
#define OK 0 
#define WARNING 4 
#define IDSIZE 16 /* number of bytes in environment ID */ 
#define TIMEDATESIZE 24 /* number of bytes in time and date */ 


int main(int argc, char *argv[]) 


{ 


long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 
char rule_array2[3] [8]; 


long verb_data_length = 0; /* currently not used by this verb 
char * verb data = " "; 


/* set keywords in the rule array 
memcpy (rule_array,"ADAPTERISTATEID ",16); 
/* get the environment ID from the card 


CSUACFQ( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&averb_data_length, 
verb_data); 
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if ( (return_code == OK) | (return_code == WARNING) ) 
soa piteniweuiet! ID was successfully returned.\n"); 
printf("Return/reason codes "); 
printf ("%ld/%ld\n\n", return_code, reason_code); 
printf("ID = %.16s\n", rule_array); 

} 

else 

{ 
printf("An error occurred while getting the environment ID.\n"); 
printf("Return/reason codes "); 


printf("%ld/%ld\n\n", return_code, reason_code); 


/* return(ERROR) */; 
} 


/* set count to number of bytes of returned data */ 


rule_array_count = 2; 


return_code = 0; 
reason_code = 0; 
/* set keywords in the rule array x*/ 


memcpy (rule_array2, "ADAPTERITIMEDATE", 16) ; 
/* get the time from the card */ 


CSUACFQ( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array2, 
&verb_data_length, 
verb_data); 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 
printf("Time and date was successfully returned.\n"); 
printf("Return/reason codes "); 


printf("%ld/%ld\n\n", return_code, reason_code) ; 


oe of 


printf ("DATE .8s\n", rule_array2); 

printf("TIME = %.8s\n", &rule_array2[1]); 

printf("DAY of WEEK = %.8s\n", &rule_array2[2]); 
} 


else 

{ 
printf("An error occurred while getting the time and date.\n"); 
printf("Return/reason codes "); 


printf ("%ld/%ld\n\n", return_code, reason_code); 
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return(ERROR) ; 
} 
} 
Example: Requesting information from your 4758 Coprocessor 


Change this program example to suit your needs for requesting information from 
your 4758 Coprocessor. 


i pecemeness hess esas ese r sae sedsens] eases =csassee eee soaseseeseses=eos= */ 
/* Query the 4758 card for status or other information. */ 
/* This sample program prompts the user for the second required */ 
/* keyword. (ADAPTER1 keyword is assumed.) x/ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: This verb is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* char * keyword2 upto 8 bytes */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CFQ) TIMEDATE */ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: x/ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(CFQ) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CFQ) MODULE(CFQ) BNDSRVPGM(QCCA/CSUACFQ) */ 
/* x/ 
/* Note: Authority to the CSUACFQ service program in the */ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic Facility Query (CSUACFQ). x/ 
/* x/ 
(hese esstesesse Seasons ase aes oese aan soak see eee eee eeeesoeeeeseaeceesese «/ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries */ 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
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/* standard return codes */ 


| ae et «/ 
#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


[Hees eeeesesn sane esses esos eee e Se nmee eee ee eee sa aes sieese esas essese «/ 
/* standard CCA parameters x/ 
[Rasa seesosseeseseteeansaestsssss esate ces ssesk sess ose se se cseeossseas «/ 


long return_code = 0; 
long reason_code = Q; 
long exit_data_length 
char exit_data[4]; 
char rule_array[18] [8]; 
long rule_array_count = 2; 


I 
ine) 
we 


| ee eae ee a eee «/ 
/* fields unique to this sample program x/ 
| Reeesaaeseieee ao asa =aeareaeetesseoseeeeesie cea seae eases ses seoSesseeeesse «/ 
long verb_data_length = 0; /* currently not used by this verb */ 
char * verb data =" "3; 

int is; 

/* check the keyboard input */ 
if (argc != 2) 


{ 


printf("You did not enter the keyword parameter.\n"); 
printf("Enter one of the following: STATCCA, STATCARD, "); 
printf("STATDIAG, STATEXPT, STATMOFN, STATEID, TIMEDATE\n"); 


return (ERROR) ; 
} 


if ( (strlen(argv[1]) > 8) | (strlen(argv[1]) < 7) ) 
ere input string is not the right length.\n"); 
printf("Input keyword must be 7 or 8 characters.\n"); 
printf("Enter one of the following: STATCCA, STATCARD, "); 
printf("STATDIAG, STATEXPT, STATMOFN, STATEID, TIMEDATE\n"); 


return(ERROR) ; 
} 


/* set keywords in the rule array x«/ 
memcpy (rule_array, "ADAPTER1 ",16); 

memcpy (&rule_array[1], argv[1], strlen(argv[1])); 

/* get the requested data from the card */ 


CSUACFQ( &return_code, 
&reason_code, 
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&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data) ; 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 


printf("Requested data was successfully returned. \n"); 

printf("Return/reason codes "); 

printf ("%ld/%ld\n\n", return_code, reason_code); 

printf("%s data = ", argv[1]); 

for (i = 0; i < 8 * rule_array_count; i++) 
printf("%c", rule_array[i / 8][i % 8]); 


printf("\n"); 
} 


else 
printf("An error occurred while getting the requested data.\n"); 
printf("You requested %s\n", argv[1]); 
printf("Return/reason codes "); 
printf ("%ld/%ld\n\n", return_code, reason_code); 


return(ERROR) ; 
} 


} 


Initialize a key store file 


A key store file is a database file that stores operational keys, i.e. keys encrypted 

under the master key. You can initialize two different types of key stores for your 
4758 Coprocessor. The 4758 Coprocessor uses one type to store PKA keys and the 
other to store DES keys. You need to initialize a key store file if you plan to store 
keys in it or if you plan to use retain keys on hardware. 


The CCA CSP creates a DB2® key store file, if one does not already exist. If a key 
store file already exists, the CCA CSP deletes the file and recreates a new one. 


To initialize a key store, you can use the 4758 Cryptographic Coprocessor 
configuration utility. Click on Manage configuration and then click on either DES 
keys or PKA keys depending upon what key store file you wish to initialize. With 
the utility, you can only initialize a file if it does not already exist. 


If you would rather write your own application to initialize a key store file, you 
can do so by using the KeyStore_Initialize (CSNBKSI) API verb. Two example 
programs are provided for your consideration. One of them is written in ILE C, 
while the other is written in ILE RPG. Both perform the same function. 


“Example: ILE C program for initializing a key store for your 4758 Coprocessor” 


Coprocessor” on page 145 
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Note: If you choose to use one of the program examples provided, change it to 
suit your specific needs. For security reasons, IBM recommends that you 
individualize these program examples rather than using the default values 


provided. 
After you create a key store for your 4758 Coprocessor, you can generate DES and 
PKA keys using |“Create DES and PKA keys” on page 147|to store in your key store 


files. 


Example: ILE C program for initializing a key store for your 4758 


Coprocessor 
Change this program example to suit your needs for initializing a key store for 
your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


[Redes see sarees ens se=esacraeseeesesee sees 6 —— sess ese sss -aeee */ 
/* Create key store files for PKA keys. */ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999, 2000 x/ 
/* */ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* */ 
/* Parameters: */ 
/* Qualified File Name x/ 
/* x/ 
/* Examples: x/ 
/* CALL PGM(INZPKEYST) PARM('QGPL/PKAFILE') */ 
/* x/ 
/* x/ 
/* Use the following commands to compile this program: x/ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(INZPKEYST) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(INZPKEYST) MODULE(INZPKEYST) + x/ 
/* BNDSRVPGM(QCCA/CSNBKS1I) x/ 
/* x/ 
/* Note: authority to the CSNBKSI service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Keystore_Initialize (CSNBKSI) x/ 
/* x/ 
Jeoses ssesoslssesSscasceesssseesesesassatesen Ssessceeseccstesecss */ 


#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 


int main(int argc, char *argv[]) 


/Seececaeessaeseeasescessns ase tetne Sess nee eee eke eee «/ 
/* standard return codes */ 
JBosasseesessotecssesecsesescessessseeesssesss sess easeessassssesecoss «/ 
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#define ERROR -1 
#define OK 0 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 


long file_name_length; 
unsigned char description[4]; 
long description_length = 0; 
unsigned char masterkey[8]; 


if(argc < 2) 
{ 


printf("File name was not specified.\n"); 
return ERROR; 


rule_array_count = 2; 
memcpy ((char*)rule_array, "CURRENT PKA ",16); 
file_name_length = strlen(argv[1]); 


CSNBKSI (&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char*)rule_array, 
&file_name_length, 
argv[1], 
&description_length, 
description, 
masterkey) ; 


if (return_code != 0) 


printf("Request failed with return/reason codes: 


return_code, reason code); 
return ERROR; 
} 
else 


{ 
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%d/%d\n", 


*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 


printf("Key store file created\n"); 
return OK; 

} 

} 


Example: ILE RPG program for initializing a key store for your 


4758 Coprocessor 


Change this program example to suit your needs for initializing a key store for 


your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


DA KRKKKKKKKK KER KKK KEK KKK KR RRR E RK KR ERR RRR RRR REE RR RRR RK ER ERR RRR 
D* INZPKAST 

Dx« 

D* Create key store files for PKA keys. 

Dx 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

Dx tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx 

D* Parameters: None 

Dx« 

D* Example: 

D* CALL PGM(INZPKEYST) ('QGPL/PKAKEYS') 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(INZPKAST) SRCFILE(SAMPLE) 
D* CRTPGM PGM(INZPKEYST) MODULE (INZPKEYST) 


Dx BNDSRVPGM(QCCA/CSNBKSI) 

Dx« 

D* Note: Authority to the CSNBKSI service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Key Store Initialize (CSNBKS1) 


Dx« 

DAKAR KKK KKKK KER KK KKK KK RRR RRR RRR KK RRR RRR RRR KR ER RRR ERR KER ERRERRRERER 
DPxeeeececosscssces cesses ssasecsscoeoseosiccscssceess 
D* Declare variables for CCA SAPI calls 

Dkeee eee epee esc e see eee eee ee ees eee eee eee eee ces 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

Dx xx Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 
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DRULEARRAY S 16 


D* ** File name length 

DFILENAMELEN S 9B 0 

D* ** File name 

DFILENAME S 21 

D* ** Description length 

DDESCRIPLEN S 9B 0 

D* ** Description 

DDESCRIP S 16 

D* xx Master key part 

DMASTERKEY Ss 24 

Dx« 

DA RRAKKKK KKK KER KKK KERR KK ERR KERR KKK RRR RK RRR KERR RRR KKK KEK REERREERK 
D* Prototype for Key Store Initialize (CSNBKSI) 

DAK RRKKKKKKK KERR KKK KKK KERR KKK KEK KK KEK KKK KKK KERR KKK KK RERERREKK 


DCSNBKSI PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DFILENMLN 9B 0 

DFILENM 21 

DDSCPLN 9B 0 

DDSCRP 16 

DMSTRKY 24 

Dx« 
P¥esesSeossasscsesscssessccscesbassse esc osesoasosscoscescueSscs 
Dx **x Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 
PeHSesssoesaesseseeseseesee se Se seo Soe Selene a Slee scesee eee ose 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH 5 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID 5 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE Ss 10 INZ('*INFO ) 
DSTACKENTRY S 10 INZ('* a) 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN il 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR KKK KKK EK KKK EKER KEK ERK RK ERE KK EK EKER KER ERR ER ERR RR EK ERE RR EKER 
Cx START OF PROGRAM * 
CR KKK KKK EK KKK KEKE KKK KERR ER ERE RK RK EKER KEK ERR ER ERK RR EK ERE RR ERERRE 
C *ENTRY PLIST 

C PARM FILENAME 

Cksceesee ctescce sce tesoee Sees ee ssl Sot SSS ce eee seco sce sce * 
Cx Set the keyword in the rule array * 
C¥saSsesessseee ses ae sass oe seas Sessa e sal SaaSe esse sas === 5-=--=5 * 
C MOVEL "PKA ' RULEARRAY 

C MOVE "CURRENT ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

(Face see see sesbseesenen esr eseseebese sees eerssesHecssccssoss * 
Cx Set the description length * 
ee * 
C Z-ADD 0 DESCRIPLEN 

Cteceees tnt eesseseeeeeesemecneese see Hs Heese ese seca Hennes * 
Cx Find the file name length * 
eee eee eee eee a * 
C EVAL FILENAMELEN = %LEN(%TRIM(FILENAME) ) 
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CR KKK KKK EK KKK KKK KR KEKE KK EK ERK KK EKER KERR EKER ER ERK RR ERE KKK ERR KEKE 


Cx Call Key Store Initialize SAPI 


* 


CR KKK KK KK KKK KKK KKK RE KER KER ERK KK RK ERE RK EKER RE KR ERKEREREKRERKERRERRERE 


C CALLP CSNBKSI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C FILENAMELEN: 
C FILENAME: 

C DESCRIPLEN: 
C DESCRIP: 

C MASTERKEY) 
Ck kSSseecaasessael-—SSSooSe * 

Cx * Check the return code * 

Ck  Keeesesesesascesssees-esse * 

C RETURNCODE IFGT 4 

Cx* Fesecsccsscessesscssesse * 

Cx * Send failure message * 

Cx* Keosevoeescebce se eeeseee * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx« 

Cx« Kesessesscecwoceocescsecs * 

Cx * Send success message * 

Cx* ee * 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C SETON LR 
Cx* 


CR KKK KKK KEK KKK EKER KKK ERK ER ERK KK RK EKER KEKE RR EK ERE RR ERE RRR KR ERR 


Cx Subroutine to send a message 


CK KKK RRR KKK KK KKK KKK KEK KEK ERK KK EKER KEK KKK KERR ER ERK RR ERE KKK ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 


CSNBKSI failed with return/reason codes 9999/9999. 


The file was succesully initialized. 


Create DES and PKA keys 


You can use your 4758 Coprocessor to 


create two types of cryptographic keys. 


* Data Encryption Standard (DES) keys base their content on a symmetric 


algorithm. This means that cryptogr 


and decrypt data. Use DES keys for 
“Work with PINs” on page 160} and 


To create DES keys with your 4758 Coprocessor, write a prog 


“Example: Creating a DES key with your 4758 Coprocessor” on 


Chap 


aphy uses the same key value to encrypt 
“Encrypt or decrypt a file” on page 154 


managing keys. 


ram or change this 
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* Public key algorithm (PKA) keys base their content on an asymmetric algorithm, 
meaning that cryptography uses different keys for encryption and decryption. 


Use PKA keys for signing files using |“Generate and verify a digital signature” 
on page 173) and for managing keys. 
To create PKA keys with your 4758 Coprocessor, write a program or change this 
“Example: Creating a PKA key with your 4758 Coprocessor” on page 151 
Note: If you choose to use the program examples provided, change them to suit 
your specific needs. For security reasons, IBM recommends that you 


individualize these program examples rather than using the default values 
provided. 


Store your DES and PKA keys in the key store file you created for them using 
“Initialize a key store file” on page 142] You can also store PKA keys in your 4758 
Coprocessor. See the 4758 information at 


http: //www.ibm.com/security/cryptocards/html/library.shtml)“ for more 
information on storing your keys in the hardware. 


Example: Creating a DES key with your 4758 Coprocessor 
Change this program example to suit your needs for creating a DES key with your 
4758 Coprocessor. 


| ee ee ee ee ee ee ee eee */ 
/* Generate DES keys in key store. */ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 

/* x/ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x*/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* x/ 
/* Parameters: x/ 
/* char * key label, 1 to 64 characters */ 
/* char * key store name, 1 to 21 characters in form 'lib/file' */ 
/* (optional, see second note below) x/ 
/* x/ 
/* Examples: x/ 
/* CALL PGM(KEYGEN) PARM('TEST.LABEL.1') */ 
/* */ 
/* CALL PGM(KEYGEN) PARM('MY.OWN.LABEL' 'QGPL/MYKEYSTORE') x/ 
/* */ 
/* Note: This program assumes the device you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic_Resource_ Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* */ 
/* If the key store name parameter is not provided, this */ 

/* program assumes the key store file you will use is x/ 
/* already identifed either by being specified on the */ 
/* cryptographic device or has been previously named */ 
/* using the Key_Store_ Designate verb. Also you must be */ 
/* authorized to add and update records in this file. */ 
/* x/ 
/* Use the following commands to compile this program: */ 
/* ADDLIBLE LIB(QCCA) x/ 
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/* CRTCMOD MODULE(KEYGEN) SRCFILE(SAMPLE) */ 


/* CRTPGM PGM(KEYGEN) MODULE(KEYGEN) + x/ 
/* BNDSRVPGM(QCCA/CSUAKSD QCCA/CSNBKRC QCCA/CSNBKGN) x/ 
/* x/ 
/* Note: authority to the CSUAKSD, CSNBKRC and CSNBKGN service */ 
/* programs in the QCCA library is assumed. x/ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Key Store Designate (CSUAKSD) */ 
/* DES Key Record Create (CSNBKRC) */ 
/* Key Generate (CSNBKGN) */ 
/* x/ 
J #epebsesreeeseseessose see seese sete oes ose te see eens see see ses */ 


#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries 


int main(int argc, char *argv[]) 


#define ERROR -1 
#define OK 0 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
long rule_array_count; 


long file_name_length; 
char key_label [64]; 


if(argce > 2) 
{ 
file_name_length = strlen(argv[2]); 


if((file_name_length > 0) && 
(file_name_length < 22)) 
{ 


rule_array_count = 1; 
CSUAKSD(&return_code, 


&reason_code, 
&exit_data_length, 


exit_data, 
&rule_array_count, 
"DES na /* rule_array, we are working with 


DES keys in this sample program ~*/ 
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&file_name_length, 
argv[2]); /* key store file name x/ 


if (return_code != 0) 


{ 
printf("Key store designate failed for reason %d/%d\n\n", 
return_code, reason code); 
return ERROR; 
} 
else 
{ 
printf("Key store designated\n") ; 
printf("SAPI returned %1d/%ld\n", return_code, reason_code); 
} 


i 


else 


printf("Key store file name is wrong length"); 
return ERROR; 


else; /* let key store file name default */ 
J Hssecwecessecssescese ssessessesssass geste sscssssessseseesoussessecas: */ 
/* Create a record in key store */ 
[eeeeesees estes eects teen sh esses ese soa eeeSeee Seat ees ese eee cee seo */ 


memset(key_label, ' ', 64); 
memcpy(key_label, argv[1], strlen(argv[1])); 


CSNBKRC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_label); 


if (return_code != 0) 


printf("Record could not be added to key store for reason %d/%d\n\n", 
return_code, reason_code); 
return ERROR; 
} 
else 
{ 
printf("Record added to key store\n"); 
printf("SAPI returned %1d/%ld\n", return_code, reason code); 


} 
[#eens tes sassee Sassen soe betes ee eee eee ete oes eee */ 
/* Generate a key */ 
/ #esserseonsscsasesesseesases ese secsesssse sees Ses scss sal Sacesees esas */ 


CSNBKGN(&return_code, 
&reason_code, 
&exit_data_length, 


exit_data, 
"OP". /* operational key is requested x/ 
"SINGLE ", /* single length key requested */ 
"DATA a /* Data encrypting key requested */ 
an /* second value must be blanks when 
key form requests only one key */ 
HNO", /* key encrypting key is null for 
operational keys */ 
"oO", /* key encrypting key is null since 
only one key is being requested «/ 
key_label, /* store generated key in key store*/ 
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} 


"\O"); /* no second key is requested */ 
if (return_code != 0) 


printf("Key generation failed for reason %d/%d\n\n", 
return_code, reason code); 

return ERROR; 

} 

else 

{ 
printf("Key generated and stored in key store\n"); 
printf("SAPI returned %1d/%ld\n\n", return_code, reason_code); 
return OK; 


} 


Example: Creating a PKA key with your 4758 Coprocessor 
Change this program example to suit your needs for creating a PKA key with your 
4758 Coprocessor. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


ee ee ee */ 
Generate PKA keys in key store. */ 
*/ 

COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 
x/ 
This material contains programming source code for your */ 
consideration. These examples have not been thoroughly */ 
tested under all conditions. IBM, therefore, cannot */ 
guarantee or imply reliability, serviceability, or function ~*/ 
of these programs. All programs contained herein are x/ 
provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
these programs and files. x/ 
x/ 
Parameters: x/ 
char * key label, 1 to 64 characters */ 
*/ 
Examples: x/ 
CALL PGM(PKAKEYGEN) PARM('TEST.LABEL.1') */ 
x/ 
Note: This program assumes the card you want to load is x/ 
already identifed either by defaulting to the CRPO1 */ 
device or has been explicitly named using the x*/ 
Cryptographic_Resource Allocate verb. Also this x/ 
device must be varied on and you must be authorized */ 
to use this device descrption. x/ 
*/ 
This program also assumes the key store file you will = */ 
use is already identifed either by being specified on ~*/ 
the cryptographic device or has been explicitly named */ 
using the Key Store Designate verb. Also you must be */ 
authorized to add and update records in this file. */ 
x/ 
Use the following commands to compile this program: */ 
ADDLIBLE LIB(QCCA) */ 
CRTCMOD MODULE(PKAKEYGEN) SRCFILE(SAMPLE) x/ 
CRTPGM PGM(PKAKEYGEN) MODULE(PKAKEYGEN) + x/ 
BNDSRVPGM(QCCA/CSNDKRC QCCA/CSNDPKG) x/ 
x/ 
Note: authority to the CSNDKRC and CSNDPKG service programs */ 
in the QCCA library is assumed. */ 
x/ 
Common Cryptographic Architecture (CCA) verbs used: x/ 
PKA_Key_Record_Create (CSNDKRC) */ 
PKA_Key Generate (CSNDPKG) */ 
*/ 
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#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries x/ 


int main(int argc, char *argv[]) 


[eeec os eee ssa sess osceesene sae e eee e eae nese eee se ee esse cone esses */ 
/* standard return codes x/ 
eS ceceesskassosssesessacs-ssess sess cesses ssseecsesasseeoesfassecas */ 


#define ERROR -1 
#define OK 0 


[$esecesoewaassssssesosseasaSsaess ese ss -4essosee ese ssassssoeslesseeas: */ 
/* standard CCA parameters x/ 
[#eseseseeSesesen essen eeea sees ede ae sae een eee oe eet «/ 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 


[Bete meee apace aes eee Se aneese ae aceae eae esos sesso — ee eSs 2555 4-—> ase «/ 
/* fields unique to this sample program */ 
[eR egceSecesosesSesessaeeade se sooacn seo seenSsee se se eae se cence seseas */ 
char key_label [64]; /x identify record in key store to 
hold generated key x/ 


#pragma pack (1) 


typedef struct rsa_key_token_header_section { 
char token_identifier; 
char version; 
short key_token_struct_length; 
char reserved 1[4]; 
} rsa_key_token_header_section; 


typedef struct rsa_private_key_ 1024 bit_section { 
char section_identifier; 
char version; 
short section_length; 
char hash_of_private key[20]; 
short reserved_1; 
short master_key_verification_pattern; 
char key_format_and_security; 
char reserved 2; 
char hash_of_key_name[20]; 
char key_usage_flag; 
char rest_of_private_key[312]; 
} rsa_private_key_1024 bit_section; 


typedef struct rsa_public_key section { 
char section_identifer; 
char version; 
short section_length; 
short reserved_1; 
short exponent_field_length; 
short modulus_length; 
short modulus_length_in_bytes; 
char exponent; 
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#p 


} rsa_public_key_section; 


struct { 
rsa_key_token_header_section rsa_header; 
rsa_private_key_1024 bit_section rsa_private_key; 
rsa_public_key_section rsa_public_key; 


} key_token; 


struct { 
short modlen; 
short modlenfld; 
short pubexplen; 
short prvexplen; 
long pubexp; 

} prvPubl; 


ragma pack () 


long key_struct_length; 
long zero = 0; 
long key_token_length; 


long regen_data_length; 
long generated_key_id_length; 


rule_array_count 
key_token_length = 0; 

memset(key_label, ' ', 64); 
memcpy(key_label, argv[1], strlen(argv[1])); 


CSNDKRC(&return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

"VO", /* rule_array x/ 
key_label, 

&key_token_length, 

"\OQ"); /* key token */ 


if (return_code != 0) 


printf("Record could not be added to key store for reason %d/%d\n\n", 
return_code, reason_code); 
return ERROR; 

} 


else 


{ 
printf("Record added to key store\n"); 
printf("SAPI returned %1d/%ld\n", return_code, reason_code); 


memset (&key_token, 0X00, sizeof (key_token)); 


key_token.rsa_header.token_identifier = OX1E; /* external token */ 
key_token.rsa_header.key_token_struct_length = sizeof(key_token); 


key_token.rsa_private_key.section_identifier = 


0x02; /* RSA private key */ 
key_token.rsa_private_key.section_length = 
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sizeof (rsa_private_key_1024 bit_section); 
key_token.rsa_private_key.key usage flag = 0X80; 


key_token.rsa_public_key.section_identifer = 0X04; /* RSA public key */ 
key_token.rsa_public_key.section_length = 

sizeof(rsa_public_key_section); 
key_token.rsa_public_key.exponent_field_length = 1; 
key_token.rsa_public_key.modulus_length = 512; 
key_token.rsa_public_key.exponent = 0x03; 


key_token_length = sizeof(key_token) ; 


printf("Key token built\n"); 


(Bs chieeer se acseeseeseesree se asese—sSse ses So se ose eeseSs eae ee asa «/ 
/* Generate a key */ 
| ee ee */ 


rule_array_count = 1; 
regen_data_length = 0; 

/* key_token_length = 64; */ 
generated_key_id_length = 2500; 


CSNDPKG(&return_code, 
&reason_code, 
&exit_data_length, 


exit_data, 

&rule_array_count, 

"MASTER ", /* rule_array */ 

&regen_data_length, 

"\O", /* regeneration_data, none needed +*/ 

&key_token_length, /* skeleton_key_token_length */ 

(char *)&key_token, /* skeleton_key_token built above */ 

"\o"" /* transport_id, only needed for 
XPORT keys */ 

&generated_key_id_length, 

key_label); /* generated _key_id, store generated 
key in key store */ 


if (return_code != 0) 

{ 
printf("Key generation failed for reason %d/%d\n\n", 
return_code, reason_code); 
return ERROR; 

} 

else 

{ 
printf("Key generated and stored in key store\n"); 
printf("SAPI returned %1d/%ld\n\n", return_code, reason code); 
return OK; 

} 

} 


Encrypt or decrypt a file 


One of the more practical uses for your 4758 Coprocessor is encrypting and 

decrypting data files. You can use one of these cryptographic methods to protect a 

file: 

* Treat the whole file as a string of bytes (which is the method the program 
example uses). 


* Encrypt each record or part of each record. 


Write your own program or change the techniques in this program |“ Example: 


Encrypting data with your 4758 Coprocessor” on page 155}to protect data in many 


different formats, not just data files. 
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Example: Encrypting data with your 4758 Coprocessor 


Change this program example to suit your needs for encrypting data with your 


4758 Coprocessor. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#include <stdio.h> 


Sample C program for enciphering data in a file. 


COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these programs. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Parameters: 

char * key label, 1 to 64 characters 

char * input file name, 1 to 21 characters (lib/file) 
char * output file name, 1 to 21 characters (lib/file) 


Example: 
CALL PGM(ENCFILE) PARM( 'MY.KEY.LABEL' 'QGPL/MYDATA' + 
'QGPL/CRYPTDATA' ) 


Note: This program assumes the device you want to use is 
already identified either by defaulting to the CRPO1 
device or has been explicitly named using the 
Cryptographic_Resource_ Allocate verb. Also this 
device must be varied on and you must be authorized 
to use this device description. 


This program assumes the key store file you will use is 
already identifed either by being specified on the 
cryptographic device or has been previously named 

using the Key Store Designate verb. Also you must be 
authorized to add and update records in this file. 


The output file should NOT have key fields since all 
data in the file will be encrypted and therefore trying 
to sort the data will be meaningless. 

(This is NOT checked by the program) 


Use the following commands to compile this program: 

ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(ENCFILE) SRCFILE(SAMPLE) 

CRTPGM PGM(ENCFILE) MODULE(ENCFILE) + 
BNDSRVPGM(QCCA/CSNBENC) 


Note: authority to the CSNBENC service program in the 
QCCA library is assumed. 


Common Cryptographic Architecture (CCA) verbs used: 
Encipher (CSNBENC) 


/* Standard I/0 header. 
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#include <stdlib.h> /* General utilities. */ 


#include <stddef.h> /* Standard definitions. x/ 
#include <string.h> /* String handling utilities. x/ 
#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 
[eseeaseceecesasscesseeeeweseeeseceaeeset See eee eee oe cee eee eS «/ 
/* Declares for working with files. x/ 
 Huseeuseeececsccssasensacssssesactesaes ss so seseces sess Seoessesseeas */ 
#include <xxfdbk.h> /* Feedback area structures. x*/ 
#include <recio.h> /* Record 1/0 routines x/ 
_RFILE xdbfptr; /* Pointer to database file. */ 
_RFILE *dbfptre; /* Pointer to database file. */ 
_RIOFB_T *db_fdbk; /* 1/0 Feedback - data base file */ 
_XXOPFB_T *db_opfb; 
_XXOPFB_T *db_opfbe; 
J $oseeeatesnssassess Sossesse Sse ssaeeeecesst scasSasesessessaoessesseeas: */ 
/* Declares for working with user space objects. */ 
[ese sbee she edeee eee eeee sees eedsecs soa eeeseee seat ae oe et «/ 


#include "qusptrus.h" 
#include "quscrtus.h" 
#include "qusditus.h" 


#define USSPC_ATTR "PF as 
#define USSPC_INIT_VAL 0x40 
#define USSPC_AUTH "*EXCLUDE " 
#define USSPC_TEXT "Sample user space" 
#define USSPC_REPLACE "*YES 7 
char space_name[21] = "PLAINTXT QTEMP "; /* Name of user 
space for plain text */ 
char cipher_name[21] = "CIPHER QTEMP "; /* Name for user 
space containing ciphertext x/ 
struct { /* Error code structure required for */ 
/* the User Space API's. */ 
int in_len; /* the length of the error code. x/ 
int out_len; /* the length of the exception data. */ 
char excp_id[7]; /* the Exception ID. */ 
char rev; /* Reserved Field. */ 
char excp_data[120]; /* the output data associated */ 
} error_code; /* the exception ID. */ 
char ext_atr[11] = USSPC_ATTR; /* Space attribute x/ 
char initial_val = USSPC_INIT_VAL; 


/* Space initial value */ 


char auth[11] = USSPC_AUTH; 

/* Space authority */ 
char desc[51] = USSPC_TEXT; 

/* Space text */ 
char replace[11] = USSPC_REPLACE; 

/*Space replace attributex/ 
J feebeeee esas se See e ease ees Sesaan secede eset eee se sesceaese seessesece */ 
/* Start of mainline code. */ 
J HesSensesesocscssesossseessasesaesssssse sees seescss sels acesees occa */ 
int main(int argc, char *argv[]) 
{ 
| ee Se ee ee eee eee ae */ 
/* standard return codes x/ 
0 a a a ee eee et «/ 


#define ERROR -1 
#define OK 0 
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long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
long rule_array_count; 


char *xuser_space_ptr; 

char xuser_space; 

char *cipher_spc; 

long file_bytes; 

long ale 

long Js 

char key_label [64]; 

long text_len, pad_character; 

char initial_vector[8]; 

char chaining_vector[18]; 
[eedes see saessecesasese saa e eee == Sea eee ee Se See eae eae =a eee eeseee */ 
/* Open database files. */ 
xe ree wees seeeeee saa ses ssse eae See SSes ea ese ee oeeeeeas sass Sese-oSees */ 

if (argc < 4) /* were the correct number 


of parameters passed? */ 


printf("This program needs 3 parameters - "); 
printf("key label, input file name, output file name\n"); 


return ERROR; 
} 


else 


{ 


file_bytes = 0; /* Set initial number of 
bytes to encipher to @ «/ 


/* Open the input file. If the file pointer, dbfptr is not 
NULL, then the file was successfully opened. */ 


if (( dbfptr = Ropen(argv[2], "rr riofb=n")) 


!= NULL) 
{ 
/ #eeeesetenseeseseteseassesase se Se ees sees este se sane ecaessueerntesees */ 
/* Determine the number of bytes that will be enciphered. x/ 
JRosesseesesscssesscsecheessasessselecsssessesacsceseenss=s--se-sses5 */ 
db_opfb = Ropnfbk( dbfptr );  /* Get pointer to the File 


open feedback area. */ 


file_bytes = db_opfb->num_records * 
db_opfb->pgm_record_len 
+15 /* 1 is added to prevent an 
end of space error */ 


j = db_opfb->num_records; /* Save number of records*/ 
JRescssossosecssesscnscssssescasceesssessesseeaeseoos-cessesessoss */ 
/* Create user space and get pointer to it. x/ 
[Rieeshece sees seeseinese sess eenseeeeSeeseeaeeee ee sho seeeseesecee «/ 

error_code.in_len = 136; /* Set length of error */ 

/* structure. x/ 


QUSDLTUS (space_name,&error_code); /* Delete the user space 
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if it already exists. */ 


/* Create the plaintext user space object */ 
QUSCRTUS(space_name,ext_atr,file_ bytes, 
&initial_val,auth, 
desc, replace,&error_code) ; 


error_code.in_len = 48; /* Set length of error 
structure */ 
QUSPTRUS (space_name, /* Retrieve a pointer to */ 
(void *)&user_space, /* the user space. */ 


(char*) &error_code) ; 


user_Space_ptr = user_space; /* Make copy of pointer */ 


error_code.in_len = 136; /* Set length of error */ 
/* structure. */ 

QUSDLTUS (cipher_name, &error_code) ; /* Delete cipher space 
if already exists. */ 


/* Create ciphertext user space object */ 
QUSCRTUS (cipher_name,ext_atr, 
file_bytes,&initial_val,auth, 
desc, replace,&error_code); 


error_code.in_len = 48; /* Set length of error */ 
/* structure */ 
QUSPTRUS (cipher_name, /* Retrieve pointer to */ 


(void *)&cipher_spc, /* ciphertext user space */ 
(char*) &error_code) ; 


Jj Poseeseresssesessasceesessecoecsass ses] Ss —S Ss 5eeseee5—5Soeeseose5 */ 
/* Read file and fill space */ 
| ee te ee */ 
for (i=1; i<=j; i++) /* Repeat for each record */ 

{ 
/* Read a record and place in user space. x/ 


db_fdbk = Rreadn(dbfptr, user_space ptr, 
db_opfb->pgm_record_len, _ DFT); 


/* Move the user space ahead the length of a record */ 
user_space_ptr = user_space_ptr + 
db_opfb->pgm_record_len; 


} 


if (dbfptr != NULL) /* Close the file. */ 
_Rclose(dbfptr) ; 

| hesessesassceeeneenh esse s=scecnSoes sae eeeeissaoeeaesoceaseaseees= «/ 
/* Encrypt data in space x/ 
[ HesSease se se se eee see ata aos eee sess a aee ee See eeeesee ee oeesee See «/ 
memset ((char *)key_label,' ',64); /* Initialize key label 

to all blanks. x/ 

memcpy((char *)key_label, /* Copy key label parm */ 


argv[1],strlen(argv[1])); 


text_len = file_bytes - 1; 
rule_array_count = 1; 

pad_character = 40; 

exit_data_length = 0; 
memset ((char *)initial_vector,'\0',8); 


/* Encipher data in ciphertext user space x/ 
CSNBENC(&return_code, 

&reason_code, 

&exit_data_length, 
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exit_data, 

key_label, 

&text_len, 

user_space, 

initial_vector, 

&rule_array_count, 

"CBC ae /* rule_array */ 
&pad_character, 

chaining_vector, 

cipher_spc ); 


if (return_code == 0) { 


[eeeestese sess seeariete sae sree eee eee se eee eet Sa eae eet eee */ 
/* Open output file */ 
| Semeee ee eeee sigs thie Sasa 5s Sea Se eases Se ae eee Saes sis eee aosess */ 


if (( dbfptre = _Ropen(argv[3], 
"wr riofb=n")) != NULL) 


db_opfbe = Ropnfbk( dbfptr );  /* Get pointer to 
the File open feedback 


area. x/ 
if(text_len % db_opfbe->pgm_record_len != 0) 
{ 
printf("encrypted data will not fit into "); 
printf("an even number of records\n"); 
if (dbfptre != NULL) /* Close the file. x/ 
_Rclose(dbfptre) ; 
| ee ee ee ee ee ee ee eee «/ 
/* Delete both user spaces. x/ 
| ee eee ee «/ 
error_code.in_len = 136; /* Set length of 
error structure. */ 
QUSDLTUS (space_name,&error_code); /* Delete the 
user space */ 
QUSDLTUS (cipher_name,&error_code); /* Delete 
ciphertext space */ 
return ERROR; 
} 
ee tee eeeessae saa esea Sessa saa Sa ec eees ren Saas eee aes -eSeaesasS */ 
/* Write data from space to file. */ 
[#hossesessess oases ese seb sees sssesassesee Sen senesceuceeseteer nee */ 
user_space_ ptr = cipher_spc; /* Save pointer to 


cipher space. */ 


j = text_len / db_opfbe->pgm_record_len; /* find 
how many records 
are needed to store 
result in output 


file x/ 
for (i=1; i<=j; i++) /* Repeat for each 
record */ 
{ 
/* Write data to output file */ 
db_fdbk = Rwrite(dbfptre, user_space ptr, 
db_opfbe->pgm_record_len); 
/* Advance pointer ahead the length of a record */ 
user_space_ptr = user_space_ptr + 
db_opfbe->pgm_record_len; 
} 
if (dbfptre != NULL) /* Close the file */ 


_Rclose(dbfptre) ; 
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} /* end of open open 
output file x/ 
else 


printf("Output file %s could not be opened\n", 


argv[3]); 
[Resenseenseceessesesssssepeeccesseeseseescecss */ 
/* Delete both user spaces. x/ 
[ ReSpasereees seis cseeeaees os Seseeeseeseseessqae= */ 
error_code.in_len = 136; /* Set length of 
error structure. */ 
QUSDLTUS (space_name,&error_code); /* Delete the 
user space */ 
QUSDLTUS (cipher_name,&error_code); /* Delete 
ciphertext space */ 
return ERROR; 
} 
} /* If return code = 0 */ 
else 


{ 
printf("Bad return/reason code : %d/%d \n", 
return_code, reason_code) ; 


eeaesecescssegsesssasasease aes seseeSsesSassee x/ 

/* Delete both user spaces. */ 

[#esceeassteesessostssecaceosce sete asese aos aeeS */ 
error_code.in_len = 136; /* Set length of 


error structure. */ 
QUSDLTUS(space_name,&error_code); /* Delete the 

user space */ 
QUSDLTUS (cipher_name,&error_code); /* Delete 

ciphertext space */ 
return ERROR; 


[xeeees ssa seaseceres ae tee aS oat seas ae See eee seme e nee eee eos sees «/ 
/* Delete both user spaces. x/ 
[eee eeseeess casesesse secs scssseeessSs Se sseeeesseekescesceeescas «/ 
error_code.in_len = 136; /* Set length of 
error structure. */ 
QUSDLTUS (space_name, &error_code) ; /* Delete the user 
space */ 
QUSDLTUS (cipher_name, &error_code) ; /* Delete ciphertext 
space */ 
} /* End of open 
input file */ 
else 


{ 
printf("Input file %s could not be opened\n", argv[2]); 


return ERROR; 


} 
} /* argv[] == null] / 
return OK; 


} 
Work with PINs 


A financial institution uses personal identification numbers (PINs) to authorize 
personal financial transactions for its customers. A PIN is similar to a password 
except that a PIN consists of decimal digits and is normally a cryptographic 
function of an associated account number. You can use your 4758 Coprocessor to 
work with PINs. 
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To work with PINs, write a program or change this program |“Example: Working 
ith PINs on your 4758 Coprocessor” 


Note: If you choose to use the program example provided, change it to suit your 
specific needs. For security reasons, IBM recommends that you individualize 
these program examples rather than using the default values provided. 


Example: Working with PINs on your 4758 Coprocessor 
Change this program example to suit your needs for working with PINs on your 
4758 Coprocessor. 


PRK KK KKKKKKK KKK KKK KERR KKK RRR RRR ERE RRR KK RRR RRR ERE ER RK RRERKERE 
F*x PINSAMPLE 
Fx 
Fx Sample program that shows the use of the appropriate 
Fx CCA Security API (SAPI) verbs for generating and verifying 
Fx PINS 
Fx 
Fx The keys are created by first building a key token 
Fx and then importing key parts using Key _Part_Import. 
Fx Four keys are created each with a different 
Fx key type - PINGEN, PINVER, IPINENC, and OPINENC. The 
Fx PINGEN key will be used to generate a Clear PIN with the 
Fx Clear_PIN Generate verb. The OPINENC key will be used 
Fx to encrypt the PIN with the Clear_PIN Encrypt verb. 
Fx The Encrypted_PIN Verify with verify that the PIN is good 
Fx using the IPINENC key (to decrypt) and the PINVER key 
Fx to verify the PIN. 
Fx 
Fx COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 
Fx 
Fx This material contains programming source code for your 
Fx consideration. These example has not been thoroughly 
Fx tested under all conditions. IBM, therefore, cannot 
Fx guarantee or imply reliability, serviceability, or function 
Fx of these programs. All programs contained herein are 
Fx provided to you "AS IS". THE IMPLIED WARRANTIES OF 
F* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
F* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
Fx these programs and files. 


Fx 

Fx 

Fx Note: Input format is more fully described in Chapter 2 of 
Fx IBM 4758 CCA Basic Services Reference and Guide 
Fx (SC31-8609) publication. 

Fx 

Fx Parameters: 

Fx none. 

Fe 

Fx Example: 

F* CALL PGM(PINSAMPLE) 

Fx 


Fx Use these commands to compile this program on iSeries: 
Fx CRTRPGMOD MODULE(PINSAMPLE) SRCFILE (SAMPLE) 
Fx CRTPGM PGM(PINSAMPLE) MODULE(PINSAMPLE) 


Fx BNDSRVPGM(QCCA/CSNBKPI QCCA/CSNBPGN + 

Fx QCCA/CSNBCPE QCCA/CSNBPVR) 

Fx 

Fx Note: Authority to the CSNBKPI, CSNBPGN, CSNBCPE, and 

Fx CSNBPVR service programs in the QCCA library is assumed. 
Fx 


F* The Common Cryptographic Architecture (CCA) verbs used are 

Fx Key Part_Import (CSNBKPI), Clear_PIN Generate (CSNBPGN) , 

Fx Clear_PIN Encrypt (CSNBCPE), and Encrypted_PIN Verify (CSNBPVR). 
Fx 

Fx Note: This program assumes the card you want to load is 
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Fx already identifed either by defaulting to the CRPO1 


Fx device or has been explicitly named using the 

Fx Cryptographic_Resource Allocate verb. Also this 

Fx device must be varied on and you must be authorized 
Fx to use this device descrption. 

Fx 


FR KK KKK K KKK KK ERK KKK RR KK RK KERR KR KEK RRR RK RRR KEK KER ERR RRR KERR ERR KRRRER 


Fx Declare parameters that are common to all of the CCA verbs 
Fx 


FR KK RK KKK KKK KKK KKK KERR KK ERK KKK KERR KR RK KKK KKK KEKE RK RRR KK KR RERRKERERE 


DRETURNCODE S 9B 0 
DREASONCODE Ss 9B 0 
DEXITDATALEN S 9B 0 
DEXITDATA S 4 
DRULEARRAYCNT S 9B 0 
DRULEARRAY S 16 

Dx« 


DAKAR KKK KKK KER KKK KERR KK ERR KERR KEKE RE RKE RRR ERE RR ER ERE ERRERKRERER 


D* Declare Key tokens used by this program 
Dx« 

DAKAR KKK KKK KER KKK KKK KK KERR KERR ERK KERR RRR RRR RRR RRR KER ERR ERR RERRER 
DIPINKEY S 64 
DOPINKEY S 64 
DPINGENKEY S 64 
DPINVERKEY S 64 
DKEYTOKEN DS 

DKEY FORM 1 1 
DKEYVERSION b} 5 
DKEYFLAG1 7 7 
DKEYVALUE 17 32 
DKEYCV 33 48 
DKEYTVV 61 64B 0 
DTOKENPART1 1 16 
DTOKENPART2 17 32 
DTOKENPART3 33 48 
DTOKENPART4 49 64 
DKEYTVV1 1 4B 0 
DKEYTVV2 5 8B 0 
DKEYTVV3 9 12B 0 
DKEYTVV4 13 16B 0 
DKEYTVV5 17 20B 0 
DKEYTVV6 21 24B 0 
DKEYTVV7 25 28B 0 
DKEYTVV8 29 32B 0 
DKEYTVV9 33 36B 0 
DKEYTVV10 37 40B 0 
DKEYTVV11 4l 44B 0 
DKEYTVV12 45 48B 0 
DKEYTVV13 49 52B 0 
DKEYTVV14 53 56B 0 
DKEYTVV15 57 60B 0 
Dx« 


DARK RKKKKKK KK ERK KK KK KKK KKK KKK ERK KK RRR KK E KKK KERR KERR KEK RRR RRR 
D* Declare parameters unique to Key Part_Import 


Dx« 

D&A KKK KKK KKK KKK KKK KEK KKK KEK KKK EK KEK KEK KKK EK ERK KR KEKR KEK KEE ER ERK ERE 
DCLEARKEY Ss 16 

Dx« 


DARK KK KKK KKK KER KKK KERR KK KERR KERR RRR KR RE RKRE RRR RRR RRR REE KEK RR ER EKER 


D* Declare parameters unique to Clear_PIN Generate, 
D* Clear_PIN Encrypt, and Encrypted_PIN_ Verify 


DARK RKKKKKKK KER KKK KK KKK KKK KKK EKER KERR KKK RRR KK KER EKER KEK RRR RRR 


DPINLEN Ss 9B 0 
DPINCKL S 9B 0 
DSEQNUMBER S 9B 0 
DCPIN S 16 
DEPIN S 16 
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DPAN S 12 


DDATAARRAY DS 

DDECTABLE 1 16 
DVALDATA 17 32 
DCLRPIN 33 48 
DPROFILE DS 

DPINFORMAT 1 8 
DFORMATCONTROL 9 16 
DPADDIGIT 17 24 
Dx« 


DA KRA KK KKK KK KER KK KEK KKK ERK KKK KKK KK RRR RRR KKK KER KEK RRR RK RRR RE REE 
D* Declare variables used for creating a control vector and 


D* clear key. 
DAK RRK KKK KKK KEK KK KEK KKK ERK KEK KKK KK RRR KEKE KKK KER KERR EER KERR RRR ERE 


DBLDKEY DS 

DLEFTHALF 1 8 
DLEFTHALFA 1 4B 0 
DLEFTHALFB 5 8B 0 
DRIGHTHALF 9 16 

Dx« 

Dx« 


DARK KKKKKKKK KER KKK KK KKK E KEKE RRR KR ERR RRR KEKE ERR RRR 


D* Prototype for Key Part Import (CSNBKPI) 


DA KRAK KARR KK KEK KKK KKK KK RRR KERR KKK KERR KR ERK KR RRR KEKE R EK 


DCSNBKPI PR 

DRETCODE 9B 0 
DRSNCODE 9B 0 
DEXTDTALEN 9B 0 
DEXTDTA 4 
DRARRAYCT 9B 0 
DRARRAY 16 
DCLRKEY 16 
DIMPKEY 64 

Dx« 


DA RRA KKKKKK KK ERK KKK KKK KERR KERR KEK KERR KER E RK RRR RER EKER 


D* Prototype for Clear PIN Generate (CSNBPGN) 


DA KRAKKKK KKK KER KKK KERR KK ER RK RR KEK KERR KERR ERK RR RERER EKER 


DCSNBPGN PR 

DRETCODE 9B 0 
DRSNCODE 9B 0 
DEXTDTALEN 9B 0 
DEXTDTA 4 
DPINGEN 64 
DRARRAYCT 9B 0 
DRARRAY 16 
DPINL 9B 0 
DPINCHKLEN 9B 0 
DDTAARRY 48 
DRESULT 16 

Dx« 


DA KRRKKKKKKK KER KEK KKK KKK KEE RK RR KEK KR ERE RRR RK RR ERR KER ERA 


Dx Prototype for Clear PIN Encrypt (CSNBCPE) 


DA KRAKKKKK KK KEK KKK KKK KK RRR KEKE KKK KERR KR ERK KR ERRERKRER 


DCSNBCPE PR 

DRETCODE 9B 0 
DRSNCODE 9B 0 
DEXTDTALEN 9B 0 
DEXTDTA 4 
DPINENC 64 
DRARRAYCT 9B 0 
DRARRAY 16 
DCLRPIN 16 
DPINPROFILE 24 
DPANDATA 12 
DSEQN 9B 0 
DEPINBLCK 8 

Dx« 
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DA RRA KKK KKK KK EKER KEK KKK KKK KEKE KKK KERR KK ERK RRR RRR RE 


D* Prototype for Encrypted PIN Verify (CSNBPVR) 


DARRAK KKK KK KK ERK KEKE KKK KERR KERR KEK KK R RRR KER KER RR ER ERE 


DCSNBPVR PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DPINENC 64 

DPINVER 64 

DPINPROFILE 24 

DPANDATA 12 

DEPINBLCK 8 

DRARRAYCT 9B 0 

DRARRAY 16 

DCHECKLEN 9B 0 

DDTAARRAY 24 

Dx« 

DA RRA KK KKK KK ERK KK EK KKK KKK KKK KEK KKK RRR KERR KEK KER KEK REE KEKE KERR RRR RERE 
Dx Declares for sending messages to job log 

DA RRR KKK KKK KER ERK KERR KK KERR KERR KEKE RRR RER KERR RRR RR ER KERR ERR RRR RER 
DFAILMESSAGE S 50 

DGOODMESSAGE S 50 

DFAILMSG DS 

DFAILMSGTEXT 1 50 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DRETSTRUCT DS 

DRETCODE 1 41 0 

DSLASH 5 5 INZ('/') 

DRSNCODE 6 9I 0 

DFAILMSGLENGTH S 9B @ INZ(49) 

DGOODMSGLENGTH S 9B 0 INZ(29) 

DMESSAGEID S 7 INZ(' r) 
DMESSAGEFILE S 21 INZ(' ") 
DMSGKEY S 4 INZ(' r) 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ") 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(Q) 

C EVAL FAILMESSAGE = '***xx*x*x* failed with return+ 
Cc /reason codes 9999/9999' 
C EVAL GOODMESSAGE = 'PIN Validation was successful' 
CR KKK KKK KEK KKK KEKE KR EKER KERR EKER KEK ER KERR ER ERR ER ERE RRR ERE RR EREREREE 
C* START OF PROGRAM * 
Cx* * 


CR KKK KKK ERK KK KKK KKK KERR ER EKER KKK EKER KER ERR ER ERR RR EK ERE RK EKER 
Cx Build a PINGEN key token 

Cx* 

CR KKK KKK KKK KK KKK KKK KEK KKK ERE KK RK ER KEK RRR KERR EK ERK RRR ERE RK EKER 


Cx Zero out the key token to start with 


C* 

C Z-ADD 0 KEYTVV1 

C Z-ADD 0 KEYTVV2 

C Z-ADD 0 KEYTVV3 

C Z-ADD 0 KEYTVV4 

C MOVE TOKENPART1 TOKENPART2 
C MOVE TOKENPART1 TOKENPART3 
C MOVE TOKENPART1 TOKENPART4 
Cx* 

Cx Set the form, version, and flag byte 

C* 

C BITON ow lai KEYFORM 

C BITON '67' KEYVERSION 
C BITON ‘I! KEYFLAG1 


iSeries: Cryptographic hardware 


Cx« 

Cx The control vector for a PINGEN key that has the key part 
Cx flag set is (in hex): 

Cx 

Cx 00227E00 03480000 00227E00 03280000 

Cx« 

Cx If each 4 byte hex part is converted to decimal you get: 
Cx* 

Cx 2260480 55050240 2260480 52953088 

Cx« 

Cx Build the control vector by placing the decimal number in 
Cx the appropriate half of the control vector field. 

CR KKK KK KKK KKK KEKE KR KK ERK ER ERK RK RK EKER KEKE RR EKER REE ER ERR RR ERR ERE 


C Z-ADD 2260480 LEFTHALFA 
C Z-ADD 55050240 LEFTHALFB 
C MOVEL LEFTHALF KEYCV 

C Z-ADD 2260480 LEFTHALFA 
C Z-ADD 52953088 LEFTHALFB 
C MOVE LEFTHALF KEYCV 

Cx« 


Cx Calculate the Token Validation value by adding every 4 bytes 
Cx and storing the result in the last 4 bytes. 


Cx« 

C ADD KEYTVV1 KEYTVV 
C ADD KEYTVV2 KEYTVV 
C ADD KEYTVV3 KEYTVV 
C ADD KEYTVV4 KEYTVV 
C ADD KEYTVV5 KEYTVV 
C ADD KEYTVV6 KEYTVV 
C ADD KEYTVV7 KEYTVV 
C ADD KEYTVV8 KEYTVV 
C ADD KEYTVV9 KEYTVV 
C ADD KEYTVV10 KEYTVV 
C ADD KEYTVV11 KEYTVV 
C ADD KEYTVV12 KEYTVV 
C ADD KEYTVV13 KEYTVV 
C ADD KEYTVV14 KEYTVV 
C ADD KEYTVV15 KEYTVV 
Cx« 

Cx Copy token to PINGENKEY 

Cx* 

C MOVE KEYTOKEN PINGENKEY 
Cx* 


CR KKK KKK EK KKK EKER RK KEK KEK ERK KK EKER KEK KEKE KR ERE RK ERE ERR ERR ERE 
Cx Build a PINVER key token 

Cx* 

Cx The control vector for a PINVER key that 

Cx has the key part flag set is (in hex): 

Cx* 

Cx 00224200 03480000 00224200 03280000 

Cx* 

Cx If each 4 byte hex part is converted to decimal you get: 
Cx* 

Cx 2260480 55050240 2260480 52953088 

Cx* 

Cx Build the control vector by placing the decimal number in 
Cx the appropriate half of the control vector field. 


C Z-ADD 2245120 LEFTHALFA 
C Z-ADD 55050240 LEFTHALFB 
C MOVEL LEFTHALF KEYCV 

C Z-ADD 2245120 LEFTHALFA 
C Z-ADD 52953088 LEFTHALFB 
C MOVE LEFTHALF KEYCV 

Cx* 


Cx Calculate the Token Validation value by adding every 4 bytes 
Cx and storing the result in the last 4 bytes. 
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C Z-ADD 0 KEYTVV 
C ADD KEYTVV1 KEYTVV 
C ADD KEYTVV2 KEYTVV 
C ADD KEYTVV3 KEYTVV 
C ADD KEYTVV4 KEYTVV 
C ADD KEYTVV5 KEYTVV 
C ADD KEYTVV6 KEYTVV 
C ADD KEYTVV7 KEYTVV 
C ADD KEYTVV8 KEYTVV 
C ADD KEYTVV9 KEYTVV 
C ADD KEYTVV10 KEYTVV 
C ADD KEYTVV11 KEYTVV 
C ADD KEYTVV12 KEYTVV 
C ADD KEYTVV13 KEYTVV 
C ADD KEYTVV14 KEYTVV 
C ADD KEYTVV15 KEYTVV 
C* 

Cx Copy token to PINVERKEY 

Cx* 

C MOVE KEYTOKEN PINVERKEY 
C* 

C* 


CR KKK KK KK EK KKK KEKE KKK KEK KKK ERE KK KKK KKK RK KERR ER ERK RR EK ERE RK EKER EK 
Cx Build an IPINENC key token 

Cx* 

Cx The control vector for an IPINENC key that 

C* has the key part flag set is (in hex): 

Cx* 

Cx 00215FO0 03480000 00215F0Q 03280000 

Cx* 

Cx If each 4 byte hex part is converted to decimal you get: 

C* 

Cx 2187008 55050240 2187008 52953088 

Cx* 

CR KKK KKK KKK KK KK KKK EK ERK EKER ERK RK EKER KEK ERR EK ERE RRR KR ERE RR EKER 
Cx Build the control vector by placing the decimal number in 


Cx the appropriate half of the control vector field. 
CR KKK KK KK EK KKK KKK KKK KEK KKK ERE KK RK ER KEK KEK ERR ER ERK EKER KERR EKER 


C Z-ADD 2187008 LEFTHALFA 
C Z-ADD 55050240 LEFTHALFB 
C MOVEL LEFTHALF KEYCV 

C Z-ADD 2187008 LEFTHALFA 
C Z-ADD 52953088 LEFTHALFB 
C MOVE LEFTHALF KEYCV 

(7 

Cx Calculate the Token Validation value by adding every 4 bytes 
Cx and storing the result in the last 4 bytes. 

Cx* 

C Z-ADD 0 KEYTVV 

C ADD KEYTVV1 KEYTVV 

C ADD KEYTVV2 KEYTVV 

C ADD KEYTVV3 KEYTVV 

C ADD KEYTVV4 KEYTVV 

C ADD KEYTVV5 KEYTVV 

C ADD KEYTVV6 KEYTVV 

C ADD KEYTVV7 KEYTVV 

C ADD KEYTVV8 KEYTVV 

C ADD KEYTVV9 KEYTVV 

C ADD KEYTVV10 KEYTVV 

C ADD KEYTVV11 KEYTVV 

C ADD KEYTVV12 KEYTVV 

C ADD KEYTVV13 KEYTVV 

C ADD KEYTVV14 KEYTVV 

C ADD KEYTVV15 KEYTVV 

C* 

Cx Copy token to IPINENC 

Cx* 
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C MOVE KEYTOKEN IPINKEY 

Cx 

Cx* 

CR K KK KR KKK KKK KEK KKK EKER KER ERK KK RK EKER KEK ERR ERE RRR ERE REE ERR ERE 
Cx Build an OPINENC key token 

Cx« 

Cx The control vector for an OPINENC key that 

C* has the key part flag set is (in hex): 

Cx« 

Cx 00247700 03480000 00247700 03280000 

Cx* 

Cx If each 4 byte hex part is converted to decimal you get: 

Cx* 

Cx 2389760 55050240 2389760 52953088 

Cx« 

CR KKK KR KKK KKK KEKE KR EKER KER ERK KEKE KKK KEKE RR ER ERR ER ERE RK RR ERR ERE 
Cx Build the control vector by placing the decimal numbers in 


Cx the appropriate half of the control vector field. 
CR KKK KKK KKK KK KKK KKK KE KK KEK ERK KK EK ERE RK RK KERR EKER KERR ERE KKK ERR ERE 


C Z-ADD 2389760 LEFTHALFA 
C Z-ADD 55050240 LEFTHALFB 
C MOVEL LEFTHALF KEYCV 

C Z-ADD 2389760 LEFTHALFA 
C Z-ADD 52953088 LEFTHALFB 
C MOVE LEFTHALF KEYCV 

Cx* 


Cx Calculate the Token Validation value by adding every 4 bytes 
Cx and storing the result in the last 4 bytes. 


Cx« 

C Z-ADD 0 KEYTVV 
C ADD KEYTVV1 KEYTVV 
C ADD KEYTVV2 KEYTVV 
C ADD KEYTVV3 KEYTVV 
C ADD KEYTVV4 KEYTVV 
C ADD KEYTVV5 KEYTVV 
C ADD KEYTVV6 KEYTVV 
C ADD KEYTVV7 KEYTVV 
C ADD KEYTVV8 KEYTVV 
C ADD KEYTVV9 KEYTVV 
C ADD KEYTVV10 KEYTVV 
C ADD KEYTVV11 KEYTVV 
C ADD KEYTVV12 KEYTVV 
C ADD KEYTVV13 KEYTVV 
C ADD KEYTVV14 KEYTVV 
C ADD KEYTVV15 KEYTVV 
Cx* 

Cx Copy token to OPINENC 

Cx« 

C MOVE KEYTOKEN OPINKEY 
Cx* 

Cx* 


(OITA III III III III IIIT IIIT ITI I I III I IK 
ra Clear key value for PINGEN/PINVER form will be: 

: 01234567 01765432 01234567 01765432 

c The key will be imported into two parts that get exclusived 
Cx OR'ed together. This program uses as key parts: 

a 00224466 00775533 00224466 00775533 and 

. 01010101 01010101 01010101 01010101 

. Converting these to decimal results in 

i: 2245734 7820595 2245734 7820595 and 
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Cx* 

Cx 16843009 16843009 16843009 16843009 

C* 

Cx In this example, the left half of the key is the same as 

Cx the right half. PIN keys in CCA are double length keys. 

Cx However, some implementation of DES (including Cryptographic 
C* Support/400) use single length keys for PINs. If both 

Cx halves of a double are the same, then they produce the 

Cx same output as a single length key, thereby allowing you 

Cx to exchange data with non-CCA systems. 

CR KKK KKK KEK KKK EKER RK K EK KKK EKER KKK ER KEK KKK KERR ER ERE RR EK ERE RK EKER RE 
Cx Import the PINGEN key 

CR KKK KK KEK EKKE KK EKER EKERERR 

C MOVEL ‘FIRST! RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

CR KKK KKK KEK KKK KEKE KK EKER KERR ERE RK EKER ERK ER ERR ER ERE RR EK ERE RR EREERE 
Cx Build the next clear key part by placing the decimal numbers 
Cx in the appropriate half of the clear key field. 


CR KKK KKK EK KKK KKK KKK KEK KKK ERE KKK ER KEK KKK KERR ER ERK RR EK ERK RR EKER E 


C Z-ADD 16843009 LEFTHALFA 
C Z-ADD 16843009 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK KEK KKK KKK KKK KEK KKK ERE KK RK ER KKK RK KERR EKER KERR EK ERE RK RRR EK 


Cx Call Key Part Import the first time for the PINGEN key 


CR KKK KK KK EK KKK KEKE KKK KER KERR ERE KKK ER KERR EK ERR ER ERR RR ER ERE RR EKER 


C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINGENKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KKK ERK KK RK EK KEK ERK ER ERE KKK ERE KR EK ERR ER ERK RR EK ERR ER EKER 


Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CR KKK KKK KEK KKK KK KEK KEK KEK KKK ERE KKK ER KEK KKK KERR EKER KERR EK ERE RR ERR RRE 


C Z-ADD 2245734 LEFTHALFA 
C Z-ADD 7820595 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK EK KKK KK KK KEK KEK KKK ERE KKK KERR KKK KERR EK ERK EKER RR EKER EK 


Cx Call Key Part Import the second time for the PINGEN key 


CR KKK KKK KEKE KK KEKE KR EKER KERR ER ERK RK EK KERR ERE RR ER ERK RR EK ERE RR ERERREE 


C MOVEL "LAST ° RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINGENKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KKK ERK KK KEKE KK EKER KER EKER KKK EKER KER ERR ER ERE RR EK ERE RR EKER 


Cx Import the PINVER key * 


CR KKK KK KK KKK KK EKER KKERERK 


iSeries: Cryptographic hardware 


LR 


LR 


C MOVEL "FIRST RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 
C Z-ADD 16843009 LEFTHALFA 

C Z-ADD 16843009 LEFTHALFB 

C MOVEL LEFTHALF CLEARKEY 

C MOVE LEFTHALF CLEARKEY 


CR KKK KK KKK KKK KEKE KR EKER KER ERK KK EKER KERR EKER ER EKER ERE REE ERR 


Cx Call Key Part Import the first time for the PINVER key 


CK KK KKK KKK KK KKK KKK KEK KKK ERK KK EKER KEK KEK KERR ERE RK RR EKER KERR ERR ERE 


C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINVERKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KKK KKK KKK KE KKK KEK KEK ERK KK RK EKER KEK KERR ERE KKK R ER EKER ERR ERE 
Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CR K KK KK KKK KKK KEKE ERK RE RK ER ERK KK RK EKER KEK ERR ER ERE RR EKER ERR ERR 


C Z-ADD 2245734 LEFTHALFA 
C Z-ADD 7820595 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KK KKK KKK KEK KKK EKER KER ERK RRR KEKE RK EKER ER ERR RR ERE REE ERR 


Cx Call Key Part Import the second time for the PINVER key 


CR KK A KKK KKK KKK KEK RK KEK KKK ERK KK EK EKER KEK EKER ERK RR ERE REE ERR ERE 


C MOVEL "LAST ; RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINVERKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KKK KKK KKK KEK RK KEK KEK ERK KK EKER KEK KKK KERR ER ERK RR ERE KERR ERR ERE 
Cx Clear key value for IPINENC/OPINENC key pair will be: 

C* 012332EF 01020408 012332EF 01020408 

Cx* 

Cx The key will be imported into two parts that get exclusived 
Cx OR'ed together. This program uses as key parts: 

Cx* 

Cx 002233EE 00030509 002233EE 00030509 and 

Cx« 

C«* 01010101 01010101 01010101 01010101 

Cx« 

Cx Converting these to decimal results in 

Cx* 

C* 2241518 197897 2241518 197897 and 

Cx* 

Cx 16843009 16843009 16843009 16843009 

CR KKK KK KKK KKK KEKE KR EKER KER ERE KK RK EKER KEKE RR EKER REE EKER ERR ERR 
Cx Import the PINVER key * 

CK KKK KKK KKK KKEKE KR KKEKERER 


C MOVEL "FIRST RULEARRAY 


LR 


LR 
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C Z-ADD 1 RULEARRAYCNT 

CR KKK KK KK EK KKK KEKE KR EKER KER ERE RK EKER ER ERR ER ERE RR EK ERE RR EKER 
Cx Build the clear key part by placing the decimal number in 

Cx the appropriate half of the clear key field. 


CR KKK KKK KEK KKK KKK KKK KEK KKK KEKE KK KEK ERK KK RK KERR ER ERK RR EK ERE RK EKER 


C Z-ADD 16843009 LEFTHALFA 
C Z-ADD 16843009 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK KEK KKK KEKE KKK KEK KKK ERE KKK KERR KKK EKER EKER KERR EK ERE RR ERE RREE 


Cx Call Key Part Import the first time for the IPINENC key 


CR KKK KKK EK KKK RK KEK KKK ERK EKER ERK RK EKER KEK ERR ER ERK RR EK ERE ER ERERREE 


C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C IPINKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KKK KEK KKK RK ERR EK ERR KER ERK RK EKER RRR ERR ER ERE RRR ERE ER ERE 


Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CR KKK KKK KEK KKK KKK KKK KEK KKK ERE KK KK ER KEK KKK KERR ER EKER KEK ERE RR EKER EK 


C Z-ADD 2241518 LEFTHALFA 
C Z-ADD 197897 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK EK KKK KKK KKK KEK KKK ERE KK KK ER KEK KKK KERR ER ERK RR EKER ERR EKER E 


Cx Call Key Part Import the second time for the IPINENC key 


CR KKK KKK KEK KKK KEKE KR KK ERR ER EKER KEK ERE RR ER ERR ER ERE RK EK ERE RR EKER 


C MOVEL "LAST : RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C IPINKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KK KEKE KKK KKK EK KEK ERK ER EK ERK EKER KERR EK ERR ER ERE RR EK ERE RR ERERREE 
Cx Import the OPINENC key * 

CR KKK KK KK KKK KK KKK KR KKERERK 

C MOVEL ‘FIRST! RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

CR KKK KKK EK KKK KKK KKK KEK KKK ERE KK KK ER KEK KKK KERR ER ERK RR EK ERE RR EKER 
Cx Build the clear key part by placing the decimal number in 

Cx the appropriate half of the clear key field. 


CR KKK KK KEK EK KKK RK EK RK KER KEK ERE KK RK ERE RR ER ERR ER ERR RR EK ERE RR EKER 


C Z-ADD 16843009 LEFTHALFA 
C Z-ADD 16843009 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK ERK KK RK E KKK KERR EK ERE RK EK EKER KER ERR ER ERE RR EK ERE RR EKER 


Cx Call Key Part Import the first time for the OPINENC key 


CR KKK KKK KEK KKK KKK KR KK ERK KK ERE KK RK ER KEK RRR ERR ER ERK RR EK ERE RR EKER EK 


C CALLP CSNBKPI (RETURNCODE: 


iSeries: Cryptographic hardware 


LR 


LR 


c REASONCODE: 
c EXITDATALEN: 
C EXITDATA: 

c RULEARRAYCNT: 
c RULEARRAY : 

c CLEARKEY: 

c OPINKEY) 

C RETURNCODE —-IFGT 4 

c MOVEL 'CSNBKPI! FAILMESSAGE 
c EXSR SNDFAILMSG 

c SETON 

c ENDIF 


CR KKK KK KEKE KKK KK KK KKK KER KER ERK KK RR EKER KEKE RR EKER KERR ERE RE RR ERREERE 
Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CRRA KR KKK KKK KE KKK KKK ERK ER ERE KK EKER RRR EKER ERE RRR ER ERR RR ERR ERE 


C Z-ADD 2241518 LEFTHALFA 
C Z-ADD 197897 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KK KKK KKK KE KKK KKK E RK ER ERK KK RK EKER KEKE RR ER ERR ERE ERE RR ERRERE 


Cx Call Key Part Import the second time for the OPINENC key 


CR KKK KKK KKK KKK KKK RK KEK KEK ERK KKK KERR KK RK EKER ER ERK ER ER ERE ERR ERE 


C MOVEL "LAST i RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXT TDATALEN: 
C EXTTDATA: 

C RULEARRAYCNT : 
C RULEARRAY : 

C CLEARKEY: 

C OPINKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 

Cx 


CR KKK KKK KKK KK KKK KR KKK KK EK ERK KK KK ER KEK KEK KERR ER ERK EKKERKERRERE 
Cx Generate a Clear PIN with CSNBPGN (Clear_PIN Generate) 

C* Rule_array_count = 1 

C* Rule_array = "IBM-PIN " (Same as Crypto Support/400) 

Cx PIN length = 8 

C* PIN Check length = 8 (But is ignored for IBM-PIN) 

Cx Data array: 

Cx Dec. table set to 0123456789123456 

C* validation dta = 1111222233334444 


Cx clear PIN = ignored 

CR KKK KK KKK KKK KEKE KR EKER KER ERK KK RK EKER KER ERR EKER REE REE REE ERRERE 
C Z-ADD 1 RULEARRAYCNT 

C MOVEL ‘IBM-PIN ! RULEARRAY 

C Z-ADD 8 PINLEN 

C Z-ADD 8 PINCKL 

C MOVEL 'Q1234567' DECTABLE 

C MOVE '89123456' DECTABLE 

C MOVEL '11112222' VALDATA 

C MOVE "33334444 ' VALDATA 


CK R KK KKK KKK KKK KKK KKK EK KEK ERK KKK KERR RRR ERR ERE RRR KER ERR RRR ERE 
Cx Call Clear PIN Generate 

CR KKK KKK KEK KKK ERK ERE KER KER ERK KK RK EKER KEKE RR ER ERR RRR ERE RR ERR 
C CALLP CSNBPGN (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
PINGENKEY: 
RULEARRAYCNT: 
RULEARRAY : 


LR 


LR 
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C PINLEN: 

C PINCKL: 

C DATAARRAY : 
C CPIN) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBPGN' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 

Cx* 

Cx* 


CR KKK KKK EK KKK RK EK KEK ERK EKER ERK RK ERR RR EKER R ER ERE RR EK ERE ERE REE 
C* Encrypt the clear PIN using CSNBCPE (Clear_PIN Encrypt) 

Cx Rule_array_count = 1 

C* Rule_array = "ENCRYPT " 

Cx PIN Profile = "3624 NONE Ee 

Cx PAN data is ignored 


Cx Sequence number is ignored but set to 99999 anyway 
CR KKK KKK KEK KKK KEKE KR KK ERK KK ERE KK RK EK KKK RK KERR EKER KERR EK ERE RK EKER EK 


C Z-ADD 1 RULEARRAYCNT 
C MOVEL "ENCRYPT ' RULEARRAY 

C MOVEL "3624 : PINFORMAT 

C MOVE "NONE ' FORMATCONTROL 
C MOVE ' F PADDIGIT 

C Z-ADD 99999 SEQNUMBER 


CR KKK KKK EK KKK KKK KKK KR ERK EKER ERK KEK ER KERR ERE RR ER ERE RK EK ERE RR EKER 


Cx Call Clear PIN Encrypt 


CR KKK KKK KEK KKK KK ERR KK EK KKK ERE KK KEK EK KEK KKK KERR EKER KERR EK ERE RR ERE RKEK 


C CALLP CSNBCPE (RETURNCODE: 
C REASONCODE: 
C EXT TDATALEN: 
C EXTTDATA: 

C OPINKEY: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CPIN: 

C PROFILE: 

C PAN: 

C SEQNUMBER: 

C EPIN) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBCPE' FAILMESSAGE 
C EXSR SNDFAILMSG 

Cc SETON 

C ENDIF 

Cx* 

Cx* 


CR KKK KKK EK KKK KK ERR KK EK KKK EKER KKK ER KEK KKK KERR ER EKER KEK ERE RR EKER 
C* Verify encrypted PIN using CSNBPVR (Encrypted_PIN Verify) 
CR KKK KKK ERK KK KEKE KKK KEK KERR ERE RK EKER KERR EK ERR ER ERE RR EK ERE RR ERERREE 


MOVEL ‘IBM-PIN ! RULEARRAY 


CALLP CSNBPVR (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
IPINKEY: 
PINVERKEY: 
PROFILE: 
PAN: 
EPIN: 
RULEARRAYCNT: 
RULEARRAY : 
PINCKL: 
DATAARRAY ) 

RETURNCODE IFGT 4 
MOVEL "CSNBPVR' FAILMESSAGE 
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LR 


LR 


C EXSR SNDFAILMSG 


C SETON LR 
C ENDIF 
Cx* 


CK KKK KKK KKK KKK KEK KEK KEK KEK ERK KKK KERR KR EK ERR ERE KERR ERE KKK ERR ERE 


Cx Send successful completion message 
CRRA KK KKK KKK KEKE KR KEKE RK ER ERK KK RK EKER KEKE RR ER ERR RR EKER RR ERR ERE 


C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 

C PARM GOODMESSAGE 

C PARM GOODMSGLENGTH 
C PARM MSGTYPE 

C PARM STACKENTRY 

C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

Cx* 

C SETON LR 
Cx« 


CR K KK KK KKK KKK KEKE KR EKER KER ERK KK EKER KER KEKE RR ERE RRR ERE RRR ERRE ERE 


Cx Subroutine to send a failure message 
CR KKK KKK KKK KKK KEK KEK KEK KEK ERK KKK KEKE KK EKER RE KERR ERE KERR ERR ERE 


C SNDFAILMSG BEGSR 


C MOVE FAILMESSAGE = FAILMSGTEXT 
C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM FAILMSG 

C PARM FAILMSGLENGTH 
C PARM MSGTYPE 

C PARM STACKENTRY 

C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


Generate and verify a digital signature 


Generating a digital signature 


You can protect data from undetected changes by including a proof of identity 
value called a digital signature. A digital signature relies on hashing and public 
key cryptography. When you sign data, you hash the data and encrypt the results 
with your private key. The encrypted hash value is called a digital signature. 


If you change the original data, a different digital signature will be generated. 


To use a PKA key to sign a file, write a program or change this program 
Signing a file with your 4758 Coprocessor” on page 174 
Verifying a digital signature 


Verifying a digital signature is the opposite of signing data. Verifying a signature 
will tell you if the signed data has changed or not. When a digital signature is 
verified, the signature is decrypted using the public key to produce the original 
hash value. The data that was signed is hashed. If the two hash values match, then 
the signature has been verified. To do this, write a program or change this 
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Note: If you choose to use the program examples provided, change them to suit 
your specific needs. For security reasons, IBM recommends that you 
individualize these program examples rather than using the default values 
provided. 


Example: Signing a file with your 4758 Coprocessor 
Change this program example to suit your needs for signing a file with your 4758 


Coprocessor. 

[PeseoRS sees acess eet ee seee eee Sete ecs ee Sees eeeseeeeec a eee ee */ 
/* Description: Digitally signs a streams file. x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 

/* x/ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* x/ 
/* Parameters: File to be signed */ 
/* File to contain signature x/ 
/* Key label of key to use */ 
/* */ 
/* Examples: x/ 
/* CALL PGM(SIGNFILE) PARM('file_to_sign' 'file_to_hold_sign' */ 
/* 'key_label'); */ 
/* */ 
/* Note: The CCA verbs used in the this program are more fully = */ 
/* described in the IBM 4758 CCA Basic Services Reference */ 
/* and Guide (SC31-8609) publication. */ 
/* */ 
/* Note: This program assumes the card you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* */ 
/* Use the following commands to compile this program: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(SIGNFILE) SRCFILE(SAMPLE) SYSIFCOPT(*IFSIO) */ 
/* CRTPGM PGM(SIGNFILE) MODULE(SIGNFILE) */ 
/* BNDSRVPGM(QCCA/CSNDDSG QCCA/CSNBOWH) x/ 
/* x/ 
/* Note: authority to the CSNDDSG and CSNBOWH service programs  */ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/*  Digital_Signature_Generate (CSNDDSG) */ 
/* One_Way_ Hash (CSNBOWH) */ 
[Poses seeeteeseec sense tee Sete Sees ee esece see sees ecet eee se cee ee */ 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries x*/ 

J Hoe ceseeesasseesseseasaseeseasseseseesstecescesosessscescee */ 

/* standard return codes */ 

[#eseteeees = seseseese esse saeeeSeee se es osese see Seen enet eee seca */ 


#define ERROR -1 
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#define OK 0 


int hash_file(long h_len, char h_out[128], FILE *t_in); 


int main(int argc, char *argv[]) 


{ 


[Hest eceseesaseeecesensscon eos eos neat ese ose eee */ 
/* standard CCA parameters x/ 
| Resnsoneossetss seceeensaestseses tessa se- shes sess ossessicecse */ 


long return_code; 
long reason_code; 
long exit_data_length 
char exit_data[2]; 
long rule_array_count = OL; 
char rule_array[1] [8]; 


I 
Oo 
rE 

we 


[Hees aeeaessssanclesesssscseeeeseseeeeese eles e sao eesasoeeecee */ 
/* parameters unique to this sample program x/ 
[RasdesesossasscsesueseeuscssescasessesacsesssSesess5esosecse */ 


long PKA_private_key_identifier_length = 64; 
char PKA_private_key_identifier[64] ; 

long hash_length = 16L; 

char hash[128] ; 

long signature_field_length = 128L; 

long signature_bit_length = OL; 

char signature_field[256]; 

char key_label [64]; 

long key_token_length = 2500L; 

char key_token[2500] ; 


FILE *file2sign; 
FILE *signature; 
int hash_return; 


if (argc < 2) 

{ 
printf("Name of file to be signed is missing."); 
return ERROR; 

} 


else if (argc < 3) 


printf("Name of file where the signature should "); 
printf("be written is missing."); 
return ERROR; 
} 
else if (argc < 4) 
{ 
printf("Key label for the key to be used for signing is missing."); 
return ERROR; 
} 


if ( (strlen(argv[3])) > 64 ) 


printf("Invalid Key Label. Key label longer than 64."); 
return ERROR; 
} 
else 
{ 
memset (PKA_private_key_ identifier, ' ', 64); 
memcpy (PKA_private_key_identifier, argv[3],strlen(argv[3])); 
} 


/* Open the file that is being signed. */ 
if ( (file2sign = fopen(argv[1],"rb")) == NULL) 
{ 
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} 


printf("Opening of file %s failed.",argv[1]); 
return ERROR; 
} 


/* Obtain a hash value for the file. */ 
hash_return = hash_file(hash_length, hash, file2sign); 


/* Close the file. */ 
fclose(file2sign); 


if (hash_return != OK) 


printf("Signature generation failed due to hash error.\n"); 


else 


/* Use CSNDDSG to generate the signature. */ 
CSNDDSG(&return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

(char *) rule_array, 
&PKA_private_key_identifier_length, 
PKA_private_key_identifier, 
&hash_length, 

hash, 

&signature_field_length, 
&signature_bit_length, 
signature_field); 


} 


if (return_code != @) 

{ 
printf("Signature generation failed with return/reason code %1d/%ld", 
return_code, reason_code); 
return ERROR; 

} 

else 

{ 
printf("Signature generation was successful."); 
printf("Return/Reason codes = %ld/%ld\n", return_code, reason_code); 
printf("Signature has length = %ld\n",signature_field_length) ; 


signature = fopen(argv[2],"wb"); 
if (signature == NULL) 
{ 


printf("Open of file %s failed.",argv[2]); 
printf("Signature was not saved."); 
return ERROR; 

} 


fwrite(signature field, 1, signature _field_length, signature); 
fclose(signature) ; 

printf("Signature was saved successfully in %s.", argv[2]); 
return OK; 


} 


int hash_file(long h_len, char h_out[128], FILE *t_in) 


{ 


[Rose seseseseseceeseeetecescoesee ses seen seseeeesee sass seas */ 
/* standard CCA parameters x/ 
i Rages sae aee Sen eeeee ae ase a eae eas as eae aoa eee */ 


long return_code; 
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long reason_code; 
long exit_data_length 
char exit_data[2]; 
long rule_array_count 
char rule_array[2] [8]; 


I 
o 


I 
ine) 
we 


[Raeesseeesssssscesteersssessessasessesesssess sesso ssesisecse */ 
long text_length; 

char text[1024]; 

long chaining_vector_length = 128; 

char chaining _vector[128] ; 


long file_length; 
fseek(t_in, 0, SEEK_END); 
file_length = ftell(t_in); 


rewind(t_in); 


text_length = fread(text, 1, 1024, t_in); 


memcpy(rule_array[0], "MD5 ", 8); 

if (file_length <= 1024) { 
memcpy(rule_array[1], "ONLY ", 8); 

} 

else { 


memcpy(rule_array[1], "FIRST ", 8); 
} 


while (file_length > 0) 


{ 

CSNBOWH(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
&text_length, 

text, 
&chaining_vector_length, 
chaining_vector, 
&h_len, 

h_out); 


if (return_code != 0) 
break; 


printf("Hash iteration worked.\n"); 
file_length -= text_length; 

if (file_length > 0) 

text_length = fread(text, 1, 1024, t_in); 


if (file_length <= 1024) { 
memcpy(rule_array[1], "LAST ". 8); 
} 


else { 
memcpy(rule_array[1], "MIDDLE ", 8); 
} 


} 
} 


if (return_code != 0) 
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printf("Hash function failed with return/reason code %1d/%ld\n", 
return_code, reason code); 
return ERROR; 
} 


else 


{ 


printf("Hash completed successfully.\n"); 
printf("hash length = %1d\n", h_len); 
printf("hash = %.32s\n\n", h_out); 

return OK; 


} 
} 


Example: Verifying a digital signature with your 4758 
Coprocessor 

Change this program example to suit your needs for verifying a digital signature 
with your 4758 Coprocessor. 


ieeteeedassasesasesSeas ser eecs asec es eesaaseseacssaeesaseseoesses= */ 
/* Description: Verifies the digital signature of an IFS file */ 
/* produced by the SIGNFILE sample program. */ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 

/* */ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* x/ 
/* Parameters: Signed file */ 
/* File containing the signature x/ 
/* Key label of the key to use */ 
/* x/ 
/* Examples: x/ 
/* CALL PGM(VERFILESIG) PARM('name_of_signed_file' + */ 
/* ‘name_of_file_w_signature' + */ 
/* 'key_label'); */ 
/* */ 
/* Note: The CCA verbs used in the this program are more fully = */ 
/* described in the IBM 4758 CCA Basic Services Reference */ 
/* and Guide (SC31-8609) publication. */ 
/* x/ 
/* Note: This program assumes the card you want to use is x*/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* Use the following commands to compile this program: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* —CRTCMOD MODULE(VERFILESIG) SRCFILE(SAMPLE) SYSIFCOPT(*IFSIO)*/ 
/* CRTPGM PGM(SIGNFILE) MODULE(SIGNFILE) + */ 
/* BNDSRVPGM(QCCA/CSNDDSV QCCA/CSNBOWH) x/ 
/* */ 
/* Note: authority to the CSNDDSV and CSNBOWH service programs  */ 
/* in the QCCA library is assumed. */ 
/* */ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Digital Signature Verify (CSNDDSV) */ 
/* One_Way Hash (CSNBOWH) */ 
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#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 

[eeoct Saseeesssesataacunnsssesssesessssseesessesssesses estas */ 

/* standard return codes x/ 

[Poses dossosscsseesese cusses sesassesesesesese esos ossesoseess */ 


#define ERROR -1 
#define OK 0 


int hash_file(long h_len, char h_out[128], FILE *t_in); 


int main(int argc, char *argv[]) 


{ 
[#ssessesessssscsessestensstsesessoesesS shes sseseseeesosecse */ 
/* standard CCA parameters x/ 
[Reeeeeeeeesseee eso chases eee sees Seen eto oeee ee */ 


long return_code; 
long reason_code; 
long exit_data_length 
char exit_data[2]; 
long rule_array_count 
char rule_array[1] [8]; 


I 
oO 
i 

we 


I 
Oo 
we 


long PKA_public_key_identifier_length = 64; 
char PKA_public_key_identifier[64] ; 

long hash_length = 16L; 

char hash[128] ; 

long signature_field_length; 

char signature_field[256]; 

char key_label [64]; 


FILE *file2verify; 
FILE *signature; 
int hash_return; 


if (argc < 2) 


printf("Name of file to be verified is missing.\n"); 
return ERROR; 

} 

else if (argc < 3) 

{ 
printf("Name of file containing the signature is missing.\n"); 
return ERROR; 

} 

else if (argc < 4) 

{ 
printf("Key label for the key to be used for verification is missing.\n"); 
return ERROR; 

} 


if (strlen(argv[3]) > 64 ) 

{ 
printf("Invalid Key Label. Key label longer than 64 bytes."); 
return ERROR; 

} 


else 
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{ 

memset (PKA_public_key_identifier, ' ', 64); 

memcpy (PKA_public_key_ identifier, argv[3], strlen(argv[3])); 
} 


/* Open the file that is being verified. */ 
if ( (file2verify = fopen(argv[1],"rb")) == NULL) 


{ 
printf("Opening of file %s failed.",argv[1]); 
return ERROR; 

} 


/* Obtain a hash value for the file. */ 
hash_return = hash_file(hash_length, hash, file2verify); 


/* Close the file. */ 
fclose(file2verify); 


if (hash_return != OK) 


printf("Signature verification failed due to hash error.\n"); 
return ERROR; 
} 
else 
{ 
signature = fopen(argv[2],"rb"); 
if (signature == NULL) 
{ 


printf("Open of signature file %s failed.",argv[2]); 
printf("Signature was not verified."); 
return ERROR; 

} 


memset(signature_field, ' ', 256); 


fseek(signature, 0, SEEK_END); 
signature _field_length = ftell(signature) ; 
rewind(signature) ; 


fread(signature_ field, 1, signature _field_length, signature); 
fclose(signature) ; 


/* Use CSNDDSV to verify the signature. */ 
CSNDDSV(&return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

(char *) rule_array, 
&PKA_public_key_identifier_length, 
PKA_public_key_identifier, 
&hash_length, 

hash, 

&signature_field_length, 
signature_field); 


} 
if (return_code != 0) 


printf("Signature verification failed with return/reason code %1d/%1d", 
return_code, reason_code); 
return ERROR; 

} 


else 


printf("Signature verification was successful."); 
printf("Return/Reason codes = %ld/%ld\n", return_code, reason_code); 
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int hash_file(long h_len, char h_out[128], FILE 


{ 


/* standard CCA parameters 


[ Heese eeeeteee shee e eae ao oe eee eS 


long return_code; 
long reason_code; 


long exit_data_length = 0; 
char exit_data[2]; 
long rule_array_count = 2; 


char rule_array[2] [8]; 


| ee ee ee eee ee eee 


long text_length; 

char text[1024]; 

long chaining_vector_length = 128; 
char chaining_vector[128] ; 


long file_length; 
fseek(t_in, 0, SEEK_END); 


file_length = ftell(t_in); 
rewind(t_in); 


text_length = fread(text, 1, 1024, t_in); 


memcpy(rule_array[0], "MD5 ". 8); 

if (file_length <= 1024) { 
memcpy(rule_array[1], "ONLY ", 8); 

} 

else { 


memcpy(rule_array[1], "FIRST ", 8); 
} 


while (file_length > 0) 


CSNBOWH(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
&text_length, 
text, 
&chaining_vector_length, 
chaining_vector, 
&h_len, 
h_out) ; 


if (return_code != 0) 
break; 


printf("Hash iteration worked.\n"); 


file_length -= text_length; 
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if (file_length > 0) 
{ 
text_length = fread(text, 1, 1024, t_in); 


if (file_length <= 1024) { 
memcpy(rule_array[1], "LAST ars 
} 


else { 
memcpy(rule_array[1], "MIDDLE ", 8); 
} 


} 
} 


if (return_code != 0) 


printf("Hash function failed with return/reason code %1d/%ld\n", 
return_code, reason_code); 
return ERROR; 


else 


printf("Hash completed successfully.\n"); 
printf("hash length = %1d\n", h_len); 
printf("hash = %.32s\n\n", h_out); 

return OK; 


} 
} 


Manage multiple 4758 Cryptographic Coprocessors 


You can have up to eight 4758 Coprocessors per system. Spreading the work across 
multiple 4758 Coprocessors and multiple jobs gives you better performance 
provided that they are all configured the same. Only one Coprocessor 
(cryptographic device description) may be allocated to a job at one time. However, 
the job can switch between Coprocessors by deallocating the current Coprocessor 
and allocating a new one. For the OS/400 SSL user, the allocation and deallocation 
of the Coprocessors is managed by the system if the SSL configuration in DCM 
indicates that more than one Coprocessor is to be used for SSL session 
establishment. 


If you configure all of the Coprocessors the same, then all operational keys will 
work identically on all of the Coprocessors. Any data encrypted on one 
Coprocessor can be decrypted on a different Coprocessor. All key store files will 
work interchangeably with any of the Coprocessors. The most important part of 
configuring the Coprocessors identically is the master keys. If you entered the 
master key in parts for one Coprocessor, you must enter the same master key parts 
for all of the other Coprocessors if you want them to work interchangeably. If a 
random master key was generated inside of the Coprocessor, then you must clone 
the master key to the other Coprocessors if you want all of the Coprocessors to 
work interchangeably. 


There may be certain situations where you do not want all of the Coprocessors to 
be configured the same. They could all have different configurations or they could 
be set up in groups where the configuration within a group is the same but 
between groups is different. For these cases, all operational keys may not work 
identically on all of the Coprocessors. Data encrypted on one Coprocessor may not 
be able to be recovered on a different Coprocessor. Also, the keystore files may not 
work interchangeably among Coprocessors. For these situations, you must keep 
track of which keystore files and operational keys will work for a given 
Coprocessor. While configuring the Coprocessors differently may limit the 
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scalability of cryptographic applications, it can provide more granularity in terms 
of security. For example, you can grant different object authorities to different 
cryptographic device descriptions. 


If you use retained PKA keys then the Coprocessors are also not interchangeable. 
Retained keys can not be exported in any manner outside of the Coprocessor. 
Therefore, any cryptographic request that uses that retained key, must be sent to 
the Coprocessor that stores the retained key. 


The following material is only applicable if you are using OS/400 applications: 
Allocating a device 


The Cryptographic_Resource_Allocate (CSUACRA) API verb is used to explicitly 
allocate a cryptographic device to your job so that the system can determine how 
to route all subsequent cryptographic requests. If you use any of the CCA API 
verbs without first explicitly using the Cryptographic_Resource_Allocate 
(CSUACRA) API verb, the system will attempt to allocate the default 
cryptographic device. The default device is the cryptographic device named 
CRPO1. It must be created by either using the Basic Configuration wizard or the 
Create Device Crypto (CRTDEVCRP) CL command. You only need to use 
CSUACRA when you wish to use a device other than the default cryptographic 
device. A device allocated to a job, either explicitly or implicitly, remains allocated 
until either the job ends or the device is deallocated using the 
Cryptographic_Resource_Deallocate (CSUACRD) API verb. Two example programs 
are provided for your consideration. One of them is written in ILE C, while the 
other is written in ILE RPG. Both programs perform the same function. 


° |“Example: ILE C program for allocating a Coprocessor” 


. : eram for allocating a Coprocessor” on 


Deallocating a device 


When you have finished using a 4758 Coprocessor, you should deallocate the 4758 
Coprocessor by using the Cryptographic_Resource_Deallocate (CSUACRD) API 
verb. A cryptographic device description can not be varied off until all jobs using 
the device have deallocated it. Two example programs are provided for your 
consideration. One of them is written in ILE C, while the other is written in ILE 
RPG. Both programs perform the same function. 


* |“Example: ILE C program for deallocating a Coprocessor” on page 188 


° : eram for deallocating a Coprocessor” on 


Example: ILE C program for allocating a Coprocessor 
Change this program example to suit your needs for allocating a Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


(#esens te cenensssstosbessn esas asece seasons Se ened aes eesasessaeseat «/ 
/* Allocate a crypto device to the job. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function x/ 
/* of these program. All programs contained herein are x/ 
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/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x*/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* */ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CRPALLOC) (CRPO2) */ 
/* */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Resource Allocate (CSUACRA). */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(CRPALLOC) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CRPALLOC) MODULE (CRPALLOC) */ 
/* BNDSRVPGM(QCCA/CSUACRA) x/ 
/* x*/ 
/* Note: Authority to the CSUACRA service program in the x/ 
/* QCCA library is assumed. x/ 
/* x*/ 
[esterase aceaes eee eee eneee cease = sec Saas Hee ae ae ees eae eee aoe as */ 


#include <string.h> 
#include <stdio.h> 
#include "csucincl.h" 


Yt a ee ee eee tet «/ 
/* standard return codes */ 
[eeeeesecesseeeae eo Saee sens sere sce see e se nese ee sean aesseee sees seas «/ 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 
long resource_name_length; 


printf("Device parameter must be specified.\n"); 
return(ERROR) ; 


/* Set the keyword in the rule array 
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memcpy(rule_array,"DEVICE ",8); 
rule_array_count = 1; 


| Reaeeeseresessa sea esanhaceaeeese ee =seee a= = sean ose sae saeeesose ease «/ 
/* Set the resource name length */ 
| a ee ee ee ee «/ 
resource_name_length = strlen(argv[1]); 

| Ree secereSe san sas esan sacs sceaae se eseece eae ae-e Sass 4SeSsoeee ease «/ 
/* Call Cryptographic Resource Allocate SAPI */ 
[fee see stesensae ep Sestel cos esas sere eeee se eee eee eee eee tse «/ 


CSUACRA( &return_code, &reason_code, &exit_data_length, 
(char *)exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(long *) &resource_name_length, 


(char *) argv[1]); /* resource name x/ 
/ Rteeeaeesee See caaeeer eace ase aeoedeeease sa aeeae aac sses—SoSSo-—-e =e ee «/ 
/* Check the return code and display the results x*/ 
[Rese sce sess eee st Seae casas eneas seeeeseeea sesso sees see See oeese ass ase «/ 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 

printf("Request was successful\n"); 

return(0K); 

} 
else 

{ 

printf("Request failed with return/reason codes: %d/%d \n", 

return_code, reason_code); 
return(ERROR) ; 
} 


Example: ILE RPG program for allocating a Coprocessor 
Change this program example to suit your needs for allocating a Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DA KRAKKKKKKK KER KKK ERK KK ERK KEKE KKK KERR RRR RRR REE RRR ERK RR ERR RRR 
D* CRPALLOC 

Dx« 

D* Sample program that allocates a crypto device to the job. 
Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx 


D* Parameters: 
D« Device Name 
Dx 
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Dx Example: 

D* CALL PGM(CRPALLOC) PARM(CRPO2) 

Dx« 

Dx Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CRPALLOC) SRCFILE (SAMPLE) 

D* CRTPGM PGM(CRPALLOC) MODULE(CRPALLOC) 


Dx BNDSRVPGM(QCCA/CSUACRA) 

Dx« 

Dx Note: Authority to the CSUACRA service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic Resource Allocate (CSUACRA) 


Dx« 

Dees SoS S2e5 25S SSeS eS oe Sa See See SoS seo See See = 
D* Declare variables for CCA SAPI calls 

PeeeSeeSaseee So cee eee eee See Se ees e ee eases 
Dx ** Return code 
DRETURNCODE S 9B 0 

Dx ** Reason code 
DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 
DRULEARRAY S 16 

D« ** Resource name length 
DRESOURCENAMLEN S$ 9B 0 

D« **x Resource name 
DRESOURCENAME S 10 

Dx« 


DAKAR KKK KKK KK ERK KEKE KKK RRR KKK KERR KERR RK RR KERR ERR ERE ERERER 


D* Prototype for Cryptographic_Resource Allocate (CSUACRA) 


DA RRRKKKKKK KK ERK KEK KKK KR RK KERR RRR KERR RR KER RR E RRR REE KEK RERREEK 


DCSUACRA PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DRSCNAMLEN 9B 0 

DRSCNAM 10 

Dx« 
[De ee 
Dx ** Declares for sending messages to the 
D* ** job log using the QMHSNDPM API 

Pesce tesa t eee steers See ee eee eee ee eee ese eee eee eee eee lee 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ry 
DSTACKENTRY S 10 INZ('* ) 
DSTACKCOUNTER S 9B © INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 
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CK KK KKK KKK KKK KEK KKK EK KEK ERK KK EKER KERR RK KERR ERE RK RRR ERE RR ERR ERE 


Cx START OF PROGRAM * 
Cx * 
Ckerebseecieseesesee sess eeSee bse see eee seeesee cee este ees * 
C *ENTRY PLIST 

C PARM RESOURCENAME 10 
Cx * 
CkSsesseeeeesesesese cess cece see e eee ote ees eee ese ese ees e ee * 
Cx Set the keyword in the rule array * 
(kee Heese es eee eee ee ei ie re eee ee eet * 
C MOVEL "DEVICE ' RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

Cx* 

Gxkeeesecsescoscceceeseessossesscsoasecs-Sscesseslssest esse * 

Cx Set the resource name length * 
CXassteeeeeeseeeses se aee chess eseeeeeseesene see eee seese sxe * 

C Z-ADD 10 RESOURCENAMLEN 

Cx 
ee ee ee * 
Cx Call Cryptographic Resource Allocate SAPI * 
CkSee See ee esee sce eS ete see sees ee eee See Soe So Sese ee See eee * 
C CALLP CSUACRA (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT : 

C RULEARRAY : 

C RESOURCENAMLEN: 

C RESOURCENAME ) 
Ckxaoceoseesesoo2-sesesees * 

Cx Check the return code * 

(Xeeese eee eecesseeseesses * 

C RETURNCODE IFGT 4 

Cx Lecce cuseacoonseae=aeo * 

Cx * Send error message * 

Cx Mekecce sess oe eee teeee * 

C MOVE MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx 

C ELSE 

Cx« 

Cx Reco e estes sees eseeseess * 

Cx * Send success message * 

C* ec a a an a * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ENDIF 

Cx* 

C SETON LR 
Cx« 


CR KKK KK KKK KKK KEKE KR EKER KER ERE KK EKER KERR EKER EKERRERERERE REE ERR ERE 


Cx Subroutine to send a message 
CR KKK KKK KKK KKK KR KR KEKE KK EK ERK KK EKER KEK KEK KERR EKER KERR ERE KERR ERR ERE 


C SNDMSG BEGSR 


C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 

C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 
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C ENDSR 

Cx 
k* 
CSUACRA failed with return/reason codes 9999/9999' 
The request completed successfully 


Example: ILE C program for deallocating a Coprocessor 
Change this program example to suit your needs for deallocating a Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


[Roses seeesseseesse aces pees sce seeene esos sehecsesHenecoessseneeceese ss «/ 
/* Deallocate a crypto device from a job. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CRPDEALLOC) (CRPO2) */ 
/* x/ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Resource Deallocate (CSUACRD). x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: x/ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(CRPALLOC) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CRPALLOC) MODULE (CRPALLOC) */ 
/* BNDSRVPGM(QCCA/CSUACRD) x/ 
/* x/ 
/* Note: Authority to the CSUACRD service program in the */ 
/* QCCA library is assumed. x/ 
/* x/ 
PR eeaee reas see seen esos SaaS eee san] ae a aa eae ase =a eee */ 


#include <string.h> 
#include <stdio.h> 
#include "csucincl.h" 


| eee ee te ee eee ee ee ee ee ee eee eee */ 
/* standard return codes */ 
0 a ee ea ee ee eee */ 


#define ERROR -l 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 
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[eee eeescese Sone ssee cscs seseeecese eee eeeee ae oeeia eee seosasn esse se «/ 
/* standard CCA parameters */ 
[Hose setae cease secsesscsseeee Ss edsaseee ae eeeae sees see sere eeseeeeseS «/ 
long return_code = 0; 

long reason_code = Q; 

long exit_data_length = 2; 


char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 
long resource_name_length; 


 $eeeeeeeseseaseosecse esas see se oe soeeete ae eee ee sae oe eee «/ 
/* Process the parameters x*/ 
| Raeceeeeeesessasenaean sacs seesse a eae eas He seas Sessa oSoeseeeeeaase «/ 
if (argc < 1) 

{ 


printf("Device parameter must be specified.\n"); 
return (ERROR) ; 


} 

[dees aeeeesescenshsesasescsesoeasseee see Soe o-oo eee ese eee «/ 
/* Set the keyword in the rule array */ 
[RaeasSeesesacscsacusensesess cssessoseas=ssess sess ssese Se eseecseseae «/ 


memcpy(rule_array,"DEVICE ",8); 
rule_array_count = 1; 


/Raee aera teee sae easeaee sare Sess eeseeree 4] = ao ae eae se see sano ease aa= «/ 
/* Set the resource name length */ 
| Raeeeeceriecesa «ios ssacnaceeseseeo eS aaeas oe sear eas se eee soe e ease «/ 
resource_name_length = strlen(argv[1]); 

| ReaSeomesesesaesehas ase ses ssessoseeseeseads=ee—saaessesseseaoeeeescee «/ 
/* Call Cryptographic Resource Deallocate SAPI */ 
| eee ee «/ 


CSUACRD( &return_code, &reason_code, &exit_data_length, 
(char *)exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(long *) &resource_name_length, 


(char *) argv[1]); /* resource name x/ 
i) Roseeereteseeacce sess eaee=seaeesesoe eee os = eS =e sae ses e esses sae seeS «/ 
/* Check the return code and display the results x*/ 
| eee ee ee es «/ 
if ( (return_code == OK) | (return_code == WARNING) ) 


{ 
printf("Request was successful\n"); 
return(0K) ; 


} 


else 
{ 
printf("Request failed with return/reason codes: %d/%d \n", 
return_code, reason_code); 
return(ERROR) ; 
} 
} 


Example: ILE RPG program for deallocating a Coprocessor 
Change this program example to suit your needs for deallocating a Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


DA KRK KK KKK KK ERK KEKE KKK REE K KERR KERR RRR ER RRR KEK RRR RRR ERR KER ERR RRR 


D* CRPDEALLOC 
Dx« 
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D* Sample program that deallocates a crypto device to the job. 
Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 


D* Parameters: 

Dx Device name 

Dx« 

Dx Example: 

D* CALL PGM(CRPDEALLOC) PARM(CRPO2) 

Dx« 

D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CRPDEALLOC) SRCFILE (SAMPLE) 

D* CRTPGM PGM(CRPDEALLOC) MODULE(CRPDEALLOC) 


Dx BNDSRVPGM(QCCA/CSUACRD) 

Dx« 

D* Note: Authority to the CSUACRD service program in the 
D« QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic Resource Deallocate (CSUACRD) 


Dx« 

Dx« 
P¥eceeSecssosccsesscssesscsscesSessseeSassseessssae 
D* Declare variables for CCA SAPI calls 

Deena esceee seen ees sae set eee eee See ce eae eee Ses 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

D* ** Exit data length 
DEXITDATALEN 5 9B 0 

D« «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Resource name length 
DRESOURCENAMLEN S 9B 0 

Dx **x Resource name 

DRESOURCENAME Ss 10 

Dx« 

DA RRKKKKKKK KK ERK KEKE KKK KERR KERR KKK RRR RK ER KEK KR ER KERR EKER REERREEK 
D* Prototype for Cryptographic_Resource Deallocate (CSUACRD) 
DA RRA KKK KKK KK ERK KK KEK KKK KKK KKK ERK KEKE RK KKK KEK KK ERE KERR KK REE 
DCSUACRD PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 
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DRARRAY 16 
DRSCNAMLEN 9B 0 
DRSCNAM 10 

Dx« 


Dx ** Declares for sending messages to the 
D* ** job log using the QMHSNDPM API 


DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B @ INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFATLRSNC 46 49 

DMESSAGEID 7 ‘INZ(' ') 

DMESSAGEFTLE 21 INZ(' r) 
DMSGKEY 4 INZ(! ') 
DMSGTYPE INZ('*INFO 
DSTACKENTRY 10 INZ('* 
DSTACKCOUNTER 9B 0 INZ(2) 
DERRCODE 
DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CK KK KKK AK KKK KKK KK KKK KKK KKK KKK ERK KK RRR KEKE KERR KKK ERR ERERERERE 
C* START OF PROGRAM * 


Cx * 


DTANANNMN 
m 
[<> 
a 


C PARM RESOURCENAME 


C MOVEL ‘DEVICE ' RULEARRAY 
C Z-ADD 1 RULEARRAYCNT 


C CALLP CSUACRD (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
RESOURCENAMLEN: 
C RESOURCENAME) 


C MOVE MSG(1) MSGTEXT 
C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 


Chapter 4. 4758 Cryptographic Coprocessor for iSeries 


191 


192 


Clone 


Cx * Send success message * 


Cx feoseeersovewceecccoseis * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

C* 

C ENDIF 

Cx 

C SETON LR 
Cx 


CR KKK KKK KKK KK KEKE KR KK ERK KK ERE KK KK ER KEK KKK KERR ER ERK RR EK ERE RR EKER EK 


Cx Subroutine to send a message 
CR KKK KKK EK KKK RK ERK EKER KERR ERE RK RK ERR KR EKER RE KR ERERKEKERE RR EKER 


C SNDMSG BEGSR 

C CALL "QMHSNDPM ' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


** 


CSUACRD failed with return/reason codes 9999/9999' 
The request completed successfully 


master keys 


Master key cloning is a method for securely copying a master key from one 4758 
Coprocessor to another without exposing the value of the master key. This is 
performed by a process of splitting the master key into n shares, where n is a 
number from 1 to 15. m shares are required to rebuild the master key in another 
Coprocessor, where m is a number from 1 to 15 and less than or equal to n. 


The term "cloning” is used to differentiate the process from "copying” because no 
one share, or any combination of fewer than m shares, provide sufficient 
information needed to rebuild the master key. 


The Coprocessor containing the master key to be cloned is referred to as either the 
master-key-share source node or the Sender. The Sender must generate a retained 
RSA key pair. This private key must also have been marked as suitable for use 
with cloning when it was generated. The key is known as either the Coprocessor 
Share Signing key or the Sender key. The Coprocessor that will receive the master 
key is referred to as either the master-key-share target node or the Receiver. The 
Receiver must also generate a retained RSA key pair and must also have been 
marked as suitable for use with cloning. This key is known as either the 
Coprocessor Share Receiving key or simply the Receiver key. 


Both the Sender and Receiver public keys must be digitally signed or certified by a 
retained private key in a Coprocessor, referred to as the public key certifying node 
or the Certifier. This retained private key is the Certifier key. It is also referred to 
as the Share Administration key. The associated public key must be registered in 
both the Sender and the Receiver before shares can be generated and received. A 
4758 Coprocessor can take on the role of Certifier only, or can it be both Certifier 
and Sender, or it can be both Certifier and Receiver. 
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As each share is generated it is signed by the Coprocessor using the Sender private 
key and encrypted by a newly generated triple DES key. The triple DES key is then 
wrapped or encrypted by the Receiver public key. 


As each share is received, the signature on the share is verified using the Sender 
public key, the triple DES key is unwrapped or decrypted using the Receiver 
private key, and the share decrypted using the triple DES key. When m number of 
shares have been received, the cloned master key will be complete within the new 
master key register of the Receiver. 


The easiest and fastest way to clone master keys is to use the 4758 Cryptographic 
Coprocessor configuration web-based utility. The utility includes Master key 
cloning advisor. To start the master key cloning advisor, follow these steps: 


1. Click on Manage configuration on the 4758 Cryptographic Coprocessor 
configuration page. 


Click on Master keys. 

Select a device. 

Enter a valid Coprocessor profile and password. 
Click on the Clone button. 


a Fon 


If you would prefer to write your own application to clone master keys, you can 
do so by using the following API verbs: 


* Cryptographic_Facility_Control (CSUACFC) 

* PKA_Key_Token_Build (CSNDPKB) (may not be needed depending upon how 
you write your application) 

* PKA_Key_Generate (CSNDPKG) 

* PKA _Public_Key_Register (CSNDPKR) 

* One_Way_Hash (CSNBOWH) 

* Digital_Signature_Generate (CSNDDSG) 

* Master_Key_Distribution (CSUAMKD) 


Nine pairs of example programs are provided for your consideration. Each pair 
contains a program written in ILE C and a program written in ILE RPG. Both 
perform the same function. 


* |“Example: ILE C program for setting the min and max values for master key 
shares in your 4758 Coprocessor” on page 194 


“Example: ILE RPG program for setting the min and max values for master ke 


shares in your 4758 Coprocessor” on page 196 


“Example: ILE C program for generating a retained key pair for cloning master 
keys” on page 199 


“Example: ILE RPG program for generating a retained key pair for cloning 
master keys” on page 203 
“Example: ILE C program for registering a public key hash” on page 210 


“Example: ILE RPG program for registering a public key hash” on page 214 


“Example: ILE C program for registering a public key certificate” on page 220 


“Example: ILE RPG program for registering a public key certificate” on page 222 


“Example: ILE C program for certifying a public key token” on page 227 
“Example: ILE RPG program for certifying a public key token” on page 231 
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“Example: ILE C program for installing a master key share” on page 249 
“Example: ILE RPG program for installing a master key share” on page 253 


The remaining two pairs of example programs are not necessary for master key 
cloning. They may be useful, however, for developing and testing the previous 
example programs. 


“Example: ILE C program for listing retained keys” on page 260 
“Example: ILE RPG program for listing retained keys” on page 262 
“Example: ILE C program for deleting retained keys” on page 265 


“Example: ILE RPG program for deleting retained keys” on page 26 


For more information on cloning master keys, refer to the |IBM 4758 PCI 
(Cryptographic Coprocessor CCA Basic Services Reference and Guide. 
Example: ILE C program for setting the min and max values for 
master key shares in your 4758 Coprocessor 


Change this program example to suit your needs for setting the min and max 
values for master key shares in your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


| HaSsewe Seseessesseuesseesessesaesseseese sos se secsecsseseceseesscee= */ 
/* Set the M-of-N values in the 4758 Coprocessor. These values are */ 
/* used in cloning of the master key. The master key is */ 
/* cryptographically split into N number of parts and M number of */ 
/* parts are needed to recover it. x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(SETMOFN) PARM(5 15) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to use x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(SETMOFN) SRCFILE(SAMPLE) */ 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


CRTPGM PGM(SETMOFN) MODULE (SETMOFN) 
BNDSRVPGM(QCCA/CSUACFC) 


Note: Authority to the CSUACFC service program in the 
QCCA library is assumed. 


The Common Cryptographic Architecture (CCA) verb used is 
Cryptographic_Facilites Control (CSUACFC). 


#include "csucincl.h" /* header file for CCA Cryptographic 


/* Service Provider for iSeries 


#include <stdio.h> 

#include <string.h> 
#include <stdlib.h> 
#include "decimal.h" 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


| Rose eaeenasecs 2o=seeeneSee =o Seeeee ee - a5 =e ae eas see ae sana eeeaeee 


long return_code = 0; 

long reason_code = Q; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 


decimal(15,5) mparm, nparm; 
long verb_data[2]; 
long verb_data_length = 8; 


/* Process parameters. Numeric parms from the command line are 
/* passed in decimal 15,5 format. The parms need to be converted 
/* to int format. 


memcpy (&mparm, argv[1],sizeof(mparm) ); 
memcpy (&nparm, argv[2],sizeof(nparm) ); 
verb_data[0] = mparm; 
verb_data[1] = nparm; 


CSUACFC( &return_code, 
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*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 


*/ 
*/ 


x/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
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&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 

(char *)rule_array, 
&verb_data_length, 

(unsigned char *)verb_data); 


| Honcwesacasessesensessessesscessessseses sees esos Sfeacea se sesssaeses */ 
/* Check the results of the call */ 
[Peso teeeseseocoustssessssetsesessress asses soseosseseca=eosesseceses */ 


if ( (return_code == OK) | (return_code == WARNING) ) 

{ 

printf("M of N values were successfully set with "); 

printf("return/reason codes %1d/%ld\n\n", 
return_code, reason_code); 

return(0K) ; 

} 


else 


printf("An error occurred while setting the M of N values.\n"); 
printf("Return/reason codes %1d/%ld\n\n", 
return_code, reason_code); 
return(ERROR) ; 
} 
} 


Example: ILE RPG program for setting the min and max values 
for master key shares in your 4758 Coprocessor 

Change this program example to suit your needs for setting the min and max 
values for master key shares in your 4758 Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DARK RKKK KKK KK ER KKK KEK KKK KR KKK KR KKK KR KEK KEK KKK KERR KEK RE RK KR RRER EKER 

D* SETMOFN 

Dx 

D* Set the M-of-N values in the 4758 Coprocessor. These values 
D* are used in cloning of the master key. The master key is 

D* cryptographically split into N number of parts and M number of 
D* parts are needed to recover it. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 

D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx 

Dx 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: M and N 

Dx« 

Dx Example: 

D* CALL PGM(SETMOFN) PARM(5 10) 

Dx« 


Dx Use these commands to compile this program on iSeries: 
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D* CRTRPGMOD MODULE(SETMOFN) SRCFILE (SAMPLE) 
D* CRTPGM PGM(SETMOFN) MODULE (SETMOFN) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 
Dx 


DARK RKKKKK KK KEK KK KKK KKK ERK KKK KKK KK ERK KEKE KKK RE RK KERR RK RR RRRRRERE 


DPeSeeecceosscsscsecese eee sosoesseseosoesessesS 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN Ss 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT Ss 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Verb data length 
DVERBDATALEN S 9B 0 

Dx ** Verb data contain M (minimum) and N (maximum) 
DVERBDATA DS 8 

DM 9B 0 

DN 9B 0 

Dx« 


DARK AKKKKK KK KEK KKK KERR KK ERK KKK KK KKK RRR KK KE KKK KER RK KERR KR ERERK 


D* Prototype for Cryptographic_Facilty_Control (CSUACFC) 


DA KRKKKKKKKK KER KKK KK KKK E RK KERR KK KERR RRR RRR REE RRR ERK ER EERE 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 8 

Dx« 
Dxeeesseosssssclacesececseecceccee Sse asecsecssosesssese esses ssse 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

(De a nn a ee ee 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID Ss 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' r) 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 


CR KKK KK KEKE KKK KEKE KKK KEK KEK ERK KKK KERR KEK KERR ER ERE RR EKER ERR ERR ERE 
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Cx START OF PROGRAM * 
CXeeSSeceacee ss sceseeseeees eel Se sce seee ese sees eeScosces secs * 

C *ENTRY PLIST 

C PARM MVALUE 15 5 
C PARM NVALUE 15 5 
(CxScteessosSsscecsee sess sctsosescsoes ese sScescesesissSeesecoscce * 
Cx Set the keyword in the rule array * 
Ckteeesese see ccecseee see eee See ee see eee ee eee ieee eee eee * 

C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "SET-MOFN' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 
Ciisesecesceseosseseenssest seen seeeee sees stsndenwe rene cceseses * 
Cx Set the verb data length to 8 * 
(Xe ee eee eee ess see see eee eee e eee eke en eee eee eee ees seeses * 

C Z-ADD 8 VERBDATALEN 

CeXee eet eke cesta eee eee ete e ee ease Shee eee eee eee ese eae ele te * 
C* Set the M and N value (Convert from decimal 15 5 to binary)* 
Cketeeesssee secre eee sce e eee eee ese see ese ee eee Sete cee eee * 

C EVAL M = MVALUE 

C EVAL N = NVALUE 


CR KKK KK KEK EK KKK KEKE KR EK ERK EKER ERK RK ERE RR EKER KER ERR RR EK ERE RR EKER 


Cx Call Cryptographic Facilty Control SAPI 


CR KKK KKK KEK KKK KKK KKK KEKE KK ERE KKK ERE KK RK KERR EK ERE RR EK ERE RR EKER EK 


C CALLP CSUACFC 
C 

C 

C 

C 

C 

C 

Cc 

Ce eee * 

Cx Check the return code * 
CxSceecscsscssescscsessese * 

C RETURNCODE IFGT 0 

C* Fe ciae ee eawenee eee oea ce * 
Cx * Send error message * 
Cx* Kose cceceesessaceaseees * 
C MOVEL MSG(1) 

C MOVE RETURNCODE 
C MOVE REASONCODE 
C EXSR SNDMSG 
C* 

C ELSE 

C* KRKKKKKEKRKEKRKEKKEKEKEKKREKKEEER 
Cx * Send success message * 
Cx* KRKKKKKEKKKKEKKKEKKEKKKKKEKE 
C MOVEL MSG(2) 

C EXSR SNDMSG 
C* 

C ENDIF 

Cx* 

C SETON 

C* 


(RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
VERBDATALEN: 
VERBDATA) 


MSGTEXT 
FAILRETC 
FAILRSNC 


MSGTEXT 


LR 


CR KKK KK KK EK KKK KEKE KK KK ERK ER ERE KK RK ER KERR EK ERR ER ERE RR EK ERE RR EKER 


Cx Subroutine to send a message 
CR KKK KKK EK KKK KKK KKK KEK KKK EKER KKK ER KEK RRR KR ER ERK R EKER RK EKER EK 


CD OD OO OI OO: 
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SNDMSG 


BEGSR 
CALL 

PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 


"QMHSNDPM! 


i 


MESSAGEID 
MESSAGEFILE 
MSGTEXT 
MSGLENGTH 
MSGTYPE 
STACKENTRY 
STACKCOUNTER 
MSGKEY 


PARM ERRCODE 


C 
C ENDSR 


** 


CSUACFC failed with return/reason codes 9999/9999. 
The request completed successfully. 


Example: ILE C program for generating a retained key pair for 
cloning master keys 

Change this program example to suit your needs for generating a retained key pair 
for cloning master keys. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


[easeeseeeaseee ees esheets lees sesh see eee eee eee cece See ees */ 
/* GENRETAIN «/ 
/* x/ 
/* Sample program to generate a retained key to be used for */ 
/* master key cloning. x«/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 x/ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. */ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* */ 
/* Parameters: RETAINED _KEY_NAME */ 
/* */ 
/* Example: */ 
/* CALL PGM(GENRETAIN) PARM(TESTKEY) */ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verbs used are */ 
/* PKA_Key_Token_Build (CSNDPKB) and PKA_Key Generate (CSNDPKG). */ 
/* x/ 
/* Use these commands to compile this program on iSeries: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(GENRETAIN) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(GENRETAIN) MODULE(GENRETAIN) */ 
/* BNDDIR(QCCA/QC6BNDDIR) x/ 
/* x/ 
/* Note: Authority to the CSNDPKG and CSNDPKB service programs x/ 
/* in the QCCA library is assumed. */ 
/* x/ 
[ee aes see seeaneeee aaa sea eer ses asa sese sae SS = ae ee eae ae ae seas */ 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 
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int main(int argc, char *argv[]) 


| a ee er «/ 
/* Declares for CCA parameters x/ 
eee eee eee ee eee ee eee ea ee */ 


long return_code = 0; 
long reason_code = Q; 
long exit_data_length = 0; 
char exit_data[4]; 
char rule_array[24]; 
long rule_array_count; 
long token_len = 2500; 
char token[2500]; 
char regen _data[4]; 
char transport_key_id[4]; 
struct { 
short modlen; 
short modlenfld; 
short pubexplen; 
short prvexplen; 
long pubexp; 
} key_struct; /* Key structure for PKA Key Token Build «/ 
long key_struct_length; 
long zero = 0; 


[een eeadsaeee asses sees ened sec seens=aen es seoeees eee ses <5 - a= as ae */ 
/* Declares for working with a PKA token x/ 
| ee te eee */ 
long pub_sec_len; /* Public section length x/ 
long prv_sec_len; /* Private section length x/ 
long cert_sec_len; /* Certificate section length */ 
long info_subsec_len; /* Information subsection length x/ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
long tempLength; /* Length variable x/ 
long tempLenl, tempLen2; /* temporary length variables x/ 


char pub_token[2500] ; 
long pub_token_len; 
long name_len; 

char name[64]; 


int i; /* Loop counter */ 
FILE «fp; /* File pointer x/ 
if (arge < 2) /* Check the number of parameters passed */ 


printf("Need to enter a private key name\n"); 
return 1; 


} 


memset (token,0,2500) ; /* Initialize token to 0 */ 
memcpy ((void*)rule_array, "RSA-PRIVKEY-MGMT",16); /* Set rule array */ 
rule_array_count = 2; 


memset(name,' ', 64); /* Copy key name parameter */ 
memcpy(name, argv[1], strlen(argv[1])); 
name_len = 64; 


| he eae «/ 

/* Initialize key structure */ 

Jeseoceecesesscosccsesenssesee «/ 

memset ((void*)&key_struct, 0, sizeof(key_struct)); 

key_struct.modlen = 1024; /* Modulus length is 1024 */ 
key_struct.pubexplen = 3; 

key_struct.pubexp = 0x01000100; /* Public exponent is 65537 x/ 


key_struct_length = sizeof(key_struct); 
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[RRR KKK EKER KKK KKK AK KKK KEK AKER KEKEREKER | 
/* Call PKA_Key_Token_Build SAPI */ 
[RRKR KK KK KK EKA K EERE IKKE AKER AKER EREREKER | 
CSNDPKB( &return_code, &reason_code, &exit_data_length, 

exit_data, 

&rule_array_count, 

rule_array, 

&key_struct_length, 

(unsigned char *)&key_struct, 

&name_len, 

name, 

&zero, /* 1 */ 

NULL, 

&zero, /* 2 */ 

NULL, 

&zero, /* 3 */ 

NULL, 

&zero, /* 4 x/ 

NULL, 

&zero, /* 5 */ 

NULL, 

&token_len, 

token); 


if (return_code != 0) 


{ 


printf("PKA Key Token Build Failed : return code %d : reason code %d\n", 


return_code, reason_code) ; 
return 1; 


} 


[BRK R KER KKK AK RRA K KKK KEK KKK K ERIK KAKA KEI K KEK AKER ARERR | 
/* Build certificate x*/ 
[ERR KKK A KKK KKK KKK KKK KKK IK KKK IKKE AKKKAKKKA KKK KEK AKEEKK KE | 
/* Determine length of token from length 
/* bytes at offset 2 and 3. 
token_len = ((256 * token[2]) + token[3]); 
/* Determine length of private key 
/* section from length bytes at offset 
/* 10. 
((256 * token[10]) + token[11]); 


prv_sec_len 


*/ 
*/ 


*/ 
*/ 
*/ 


/* Determine length of public key section*/ 


/* section from length bytes at offset 
/* 10 + private section length 
((256 * token[prv_sec_len + 10]) + 
token[prv_sec_len + 11]); 


pub_sec_len 


*/ 
*/ 


/* Calculate the signature section length*/ 


cert_sec_len = 328 + /* from the signature subsection length, */ 
20 + /* EID subsection length, */ 
12 + /* Serial number subsection length, */ 
4 + /* Information subsection header length, */ 
pub_sec_len + /* Public key subsection length,  */ 
4; /* and the certificate section hdr length*/ 
offset = token_len; /* Offset for additions to token */ 
/* Fill in certicate section header */ 


tempLenl = cert_sec_len; 
tempLenl >>= 8; 


token[offset++] = 0x40; 
token[offset++] = 0x00; 
token[offset++] = tempLenl; 
token[offset++] = cert_sec_len; 


/* Fill in public key subsection */ 
token[offset++] = 0x41; 
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for (i = 1; i < pub_sec_len ; i ++) 
{ 
/* Copy public key to certificate */ 
token[offsett++] = token[prv_sec_len +(i+8)]; 
} 


/* Fill Optional Information Subsection Header */ 


info_subsec_len = 20 + /* Length of EID section x/ 
12 + /* Length of serial number section x/ 
4; /* Length of Info subsection header */ 


tempLenl = info_subsec_len; 
tempLenl >>= 83 


token[offset++] = 0x42; 
token[offsett+] = 0x00; 
token[offset++] = tempLen1; 
token[offsett++] = info_subsec_len; 
/* Fill in Public Key Certficate EID subsection */ 
token[offsett+] = 0x51; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offsett++] = 0x14; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 

/* Public key Certificate Serial Number TLV */ 
token[offset++] = 0x52; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x0c; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 

/* Fill in Signature Subsection */ 
token[offset++] = 0x45; 
token[offsett+] = 0x00; 
token[offsett+] = 0x01; 
token[offsett+] = 0x48; 
token[offset++] = 0x01; 
token[offset++] = 0x01; 


for (i = © ; i < 64 ;it+) 
{ 
/* Copy private key name out of private key name section */ 
/* into certificate «/ 
token[offset++] = 
token[prv_sec_len + pub_sec_len + 12 + i]; 
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} 


} 


token_len = offset + 258; 
token[3] = token_len; 
token[2] = token_len >> 8; 


/* add 258 to allow for digtal sig. */ 
/* Set new token length */ 


[KEK KRR KKK AK KERR RK AK KEK KK EK KKK KKK EKA KKK IKKE KAKA AKER AKER AKER | 
/* Generate Retained key using PKA token with certificate x/ 
[RRR KKK KKK A KKK KK KAKA KKK KKK KK KKK KKK KKK KKK A KKK KIER AKER AKER | 
memcpy((void*)rule_array,"RETAIN CLONE ",16); 

rule_array_count = 2; 

memset (pub_token,0,2500) ; 

pub_token_len = 2500; 

memset (transport_key_id,0,4); 


[BRK RKKRR KK EAR KER EKER A KER KKK AEE EAE KERRIER | 


/* Call PKA_Key Generate SAPI */ 


[KEK RK KEK K KEKE KEK KKK KKK ERK KEK KKK EK KK ERK | 


CSNDPKG( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
rule_array, 

&zero, 
regen_data, 
&token_len, 
token, 
transport_key_id, 
&pub_token_len, 
pub_token) ; 


/* regenerated data length */ 


if (return_code != Q) 
{ 
printf("PKA Key Generate Failed : return code %d :reason code %d\n", 
return_code, reason_code); 
return 1; 


} 


[RRR KKK KKK A KKK KKK KKK KKK IKK KK KKK KKK AK KIA KKK AKIRA AKER AKER KKK | 


/* Write public key token out to file */ 

[KEK KRR AKER IKKE IKK A KKK KEK KKK KKK IKEA KKK AK KAKA AKER AKER AKER | 
/* Append ".PUB" to key name */ 

memcpy ((void*) &mame[strlen(argv[1])],".PUB",5); 

fp = fopen(name,"wb"); /* Open the file */ 

if (!fp) 


printf("File open failed\n"); 
} 


else 
fwrite(pub_token,pub_token_len,1,fp); /* Write token to file */ 


fclose(fp); /* Close the file «/ 
printf("Public token written to file %s.\n",name) ; 


} 


name[strlen(argv[1])] = 0; /* Convert name to string */ 
printf("Private key %s is retained in the hardware\n",name) ; 
return 0; 


Example: ILE RPG program for generating a retained key pair for 


cloning master keys 


Change this program example to suit your needs for generating a retained key pair 


for cloning master keys. 
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Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 


KKKKKKK KKK KERR KKK KE KK KK KKK KR KKK KKK KKK KKK KKK KKK KRKEKKERKRRRRERKEERE 


GENRETAIN 


Sample program to generate a retained key to be used for 
master key cloning. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these programs. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 


D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 

Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
D* IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

D* Parameters: RETAINED KEY NAME 

Dx« 

Dx Example: 

D* CALL PGM(GENRETAIN) PARM(TESTKEY) 

Dx« 

D* Use these commands to compile this program on iSeries: 

D* CRTRPGMOD MODULE(GENRETAIN) SRCFILE(SAMPLE) 

D* CRTPGM PGM(GENRETAIN) MODULE (GENRETAIN) 

Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

Dx Note: Authority to the CSNDPKG and CSNDPKB service programs 
Dx in the QCCA library is assumed. 

Dx« 

D* The Common Cryptographic Architecture (CCA) verbs used are 
D* PKA Key Token Build (CSNDPKB) and PKA Key Generate (CSNDPKG). 
Dx« 

DA RRR KKK KKK KK ERE KKK KKK KERR KEKE KKK RRR RRR RRR KR ERE RR ER KERR ERRE REE 
[De en a ee et 

D* Declare variables used by CCA SAPI calls 
DeeSeeSeesscsscessooescsscescessesscsssscoseesasoassesceece 

Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

D* ** Exit data length 

DEXITDATALEN S 9B 0 

D* «x Exit data 

DEXITDATA Ss 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D« ** Token length 

DTOKENLEN S 9B 0 INZ(2500) 

D* ** Token and array for subscripting 

DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

D* *x Regeneration data 

DREGENDATA S 4 INZ(X'Q0000000' ) 

D* ** Transport key encrypting key 
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DTRANSPORTKEK 
Dx 

DGENKEY 

Dx« 
DGENKEYLEN 
Dx« 
DKEYNAME 
DKEYNAMEL 
Dx 
DKEYSTRUCT 
DMODLEN 
DMODLENFLD 
DPUBEXPLEN 
DPRVEXPLEN 
DPUBEXP 

Dx 

DZERO 
DNULLPTR 
Dx 
DKEYSTRUCTLEN 
Dx« 

Dx« 
DLENSTRUCT 
DMSB 

DLSB 
DLENGTH 

Dx« 
DPRVSECLEN 
Dx« 
DPUBSECLEN 
Dx« 

DINDEX 

Dx« 
DNAMEPTR1 
DNAME1 
DNAMEPTR2 
DNAME2 

Dx 

DI 

Dx 

DFILED 

Dx« 

DPATH 
DPATHLEN 
Dx« 

Dx 

DOFLAG 

Dx« 


4 INZ(X'Q0000000' ) 

Generated keyid 
2500 

Generated keyid length 

9B 0 INZ(2500) 
Key name and length 

64 

9B 0 INZ(64) 
Key structure for PKA Key Token Build 


oN nwr 
for) 
w 
ooooo 


12B 
Null parms needed for CSNDPKB and CSNDPKG 
9B 0 INZ(O) 
*  INZ(*NULL) 
Key structure length 
9B 0 INZ(12) 
Data structure for aligning 2 bytes into 
a 2 bytes integer 
2 


1 1 
2 2 
1 2B 0 
Private key section length 
9B 0 
Public key section length 
9B 0 
Index into Token array 
9B 0 


Declares for copying private key name 
* 


64 BASED (NAMEPTR1) 
* 
64 BASED (NAMEPTR2) 
Loop counter 
9B 0 
File descriptor 
9B 0 
File path and length 
80 INZ(*ALLX'00') 
9B 0 
Open flag - Create on open, open for writing, 
and clear if exists 
101 @ INZ(X'4A') 


DAKAR KKKKK KKK ERK KEKE KKK KERR KER ERK KERR RRR RRR REE RRR ERK ER EERE 


D* Prototype for PKA_Key Token Build (CSNDPKB) 


DAKAR KKKKKKK KER KKK KKK KR KE KEKE K KERR KERR RRR RRR RR RRR KR ER KERR ERE 


DCSNDPKB 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DRARRAYCT 
DRARRAY 
DKEYSTRLEN 
DKEYSTR 
DKEYNML 
DKEYNM 
DRSRVLN1 
DRSRV1 
DRSRVLN2 
DRSRV2 
DRSRVLN3 


PR 


) 
9B 0 
) 


* VALUE 


* VALUE 
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DRSRV3 * VALUE 


DRSRVLN4 9B 0 

DRSRV4 * VALUE 

DRSRVLN5 9B 0 

DRSRV5 * VALUE 

DTKNLEN 9B 0 

DTKN 2500 OPTIONS (*VARSIZE) 
Dx« 


DARK AKKKKKKK KER KKK KEK KKK KKK KKK KEK K KK R KEK KKK KKK REE RRR ERK RRR REREKEK 


D* Prototype for PKA Key Generate (CSNDPKG) 


DA RRA KK KKK KKK ERK KK EK KKK KKK KKK KEK K KEKE KEK KERR KKK KERR KR RR KK RRR 


DCSNDPKG PR 

DRETCOD 9B 0 

DRSNCOD 9B 0 

DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DREGDTAL 9B 0 

DREGDTA 20 OPTIONS (*VARSIZE) 
DSKTKNL 9B 0 

DSKTKN 2500 OPTIONS (*VARSIZE) 
DTRNKEK 64 OPTIONS (*VARSIZE) 
DGENKEYL 9B 0 

DGENKEY 2500 OPTIONS (*VARSIZE) 

Dx« 

DARA KK KKK KKK KER KKK ERK KK ERK KERR RRR KERR KERR KEK KR ERR KR ER KER RERERREK 
D* Prototype for open() 

DARK RK KK KKK KK ER KKK KEK KKK KKK KEKE KKK KERR KK RR KK KR ERR KR EKR KK KERR KEK 
Dx value returned = file descriptor (OK), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

D* Open flags 

D 9B @ VALUE 

D« (OPTIONAL) mode - access rights 

D 10U @ VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U 0 VALUE OPTIONS (*NOPASS) 
Dx« 


DA RRR KKK KKK KK ERK KK KEK K KK ERR KERR KR RRR KK ER KER RRR KERR EER KER RER KEK RR RERRRRRERRERE 
D* Prototype for write() 

DARK RKKKKKKK KER KK KERR KK KKK KKK KEK K KKK KEK KERR KEK KERR RRR RE EKR KK RERKEKEK 

Dx value returned = number of bytes actually written, or -1 


Dwrite PR 9B 0 EXTPROC('write') 
D« File descriptor returned from open() 

D 9B 0 VALUE 

D« Data to be written 

D 1200 OPTIONS (*VARSIZE) 
D* Length of data to write 

D 9B 0 VALUE 

Dx« 


DA RRRK KK KKK KK ERK KK KEK KKK KKK KK RR KK KERR KK ERK RR ERK KK RRR KERR KKK ERR RRREK KKK 


D* Prototype for close() 


DA RRKKKK KKK KK ERK KEKE KKK KERR KER KEK RRR RRR KER KR RRR RRR RRR RRR KERR RRR 
D« value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

D« File descriptor returned from open() 

D 9B @ VALUE 

Dx« 

DeesSeaaesa ese See S-S Sse See See e eae as Sa SSeS Sse ae aia =a = Sas aes == 
Dx **x Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Pxeiceeeccsseee ete e ese cee eee eee eee eee eee eee eee eee ece 
DMSG Ss 75 DIM(4) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 
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DMSGTEXT 1 75 


DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID Ss 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO MY 
DSTACKENTRY S 10 INZ('* ry 
DSTACKCOUNTER Ss 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 

CR KKK KKK KKK KK KKK KKK KEK KEK ERK KK RK ERR KK RK RRR ERE RRR KEKE KKK ERR ERE 
Cx START OF PROGRAM * 
Cx* * 
C *ENTRY PLIST 

C PARM KEYNAMEPARM 50 
Cx« Koseesesscsscsscsscsscose * 

Cx  »* Initialize tokens to 0 * 

Cx* occ en senses ceseesessias * 

C MOVEL *ALLX'00' TOKEN 

C MOVEL *ALLX'00' GENKEY 

Cx« Foseesessesescsssssscsssss * 

Cx  »* Initialize key struct * 

Cx« occ iee ace seeeceescosieesad * 

C Z-ADD 1024 MODLEN 

C Z-ADD 0 MODLENFLD 

C Z-ADD 3 PUBEXPLEN 

¢ Z-ADD 0 PRVEXPLEN 

C EVAL PUBEXP = 65537 * 256 

Cx« hesessccsccsesssssssscsss * 

Cx »* Copy key name from parm* 

Cx* Ceiba eee eee sed * 

C MOVEL KEYNAMEPARM KEYNAME 

Cx Ceeeeot sae seco cet eeeee ses otoeeseeewee * 

Cx »* Set the keywords in the rule array * 

Cx« esse sscescsscesceesecssssescosseoss se * 

C MOVEL "RSA-PRIV' RULEARRAY 

€ MOVE "KEY-MGMT ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 


CR KKK KKK KKK KKK KR KR KEKE KK EK ERK KK EKER KERR RK KERR EKER KER EKER KER ERR ERE 

C* Call PKA_Key_Token_Build SAPI 

CR KKK KK KKK KKK KEKE KR EKER KER ERK KK RK EKER KEK ERR ER ERE RR ERE REE ERR ERE 

CALLP CSNDPKB (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT : 
RULEARRAY : 
KEYSTRUCTLEN: 
KEYSTRUCT: 
KEYNAMEL: 
KEYNAME: 
ZERO: 
NULLPTR: 
ZERO: 
NULLPTR: 
ZERO: 
NULLPTR: 
ZERO: 
NULLPTR: 
ZERO: 
NULLPTR: 
TOKENLEN: 
TOKEN) 


AOIDODO|’OG AAA AAAMAQANADMAAaGaADAAa 
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Cx Fessesstesheeeeesessenees * 

C RETURNCODE IFGT 0 

Cx* tase cee sees eseeeescees= * 

Cx * Send failure message * 

C* (osoeece cose eweecsomes: * 

C MOVEL MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNDPKB' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 

Chee srese eee eeeee ee eee ese e eee ee ceeeee ees ese ee eHeee eee ete nese * 
Cx Build the certificate * 
Ckseee soe ceceeceeeeses soot ocecee eee se esse spaces Sse eee cesee * 


Cx Get the private section length. The length is at position 11 
Cx of the token 


C EVAL MSB = TOKENARRAY(10+1) 
C EVAL LSB = TOKENARRAY (11+1) 
C MOVE LENGTH PRVSECLEN 


Cx Get the public section length. The length is at position 
Cx (11 + Private key section length). 


Cc EVAL MSB = TOKENARRAY(10 + PRVSECLEN + 1) 
C EVAL LSB = TOKENARRAY(11 + PRVSECLEN + 1) 
C MOVE LENGTH PUBSECLEN 

Cx Calculate the certificate section length 

Cx Cert Section length = Signature length (328) + 

Cx EID section length (20) + 

Cx Serial number length (12) + 

Cx Info subsection header length (4) + 
Cx Public Key section length + 

Cx Cert section header length (4) 

C EVAL LENGTH = 328 + 20 + 12 + 4 + PUBSECLEN + 4 
Cx Fill Certificate section header 

C MOVE TOKENLEN INDEX 

C EVAL TOKENARRAY (INDEX +1) = X'4Q' 

C EVAL TOKENARRAY (INDEX +2) = X'QQ' 

C EVAL TOKENARRAY (INDEX +3) = MSB 

C EVAL TOKENARRAY (INDEX +4) = LSB 

Cx Fill in public key subsection 

C EVAL TOKENARRAY (INDEX +5) = X'41' 

C ADD 5 INDEX 

C Z-ADD 1 I 

Cx Copy the public key section of the token into the public key 
Cx subsection of the certificate section. 

C I DOWLT PUBSECLEN 

C EVAL TOKENARRAY (INDEX + I) = 

C TOKENARRAY (PRVSECLEN + I + 8 + 1) 

C 1 ADD I I 

C ENDDO 

C EVAL INDEX = INDEX + PUBSECLEN - 1 

Cx Fill in Optional Information subsection header 

C Z-ADD 36 LENGTH 

C EVAL TOKENARRAY (INDEX +1) = X'42' 

C EVAL TOKENARRAY (INDEX +2) = X'QQ' 

C EVAL TOKENARRAY (INDEX +3) = MSB 

C EVAL TOKENARRAY (INDEX +4) = LSB 

Cx Fill in Public Key Certficate EID 

C EVAL INDEX = INDEX + 4 

C EVAL TOKENARRAY (INDEX +1) = X'51' 

C EVAL TOKENARRAY (INDEX +4) = X'14' 

Cx Fill in Public Key Certficate Serial Number TLV 

C EVAL INDEX = INDEX + 20 

C EVAL TOKENARRAY (INDEX +1) = X'52' 
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+ 


~ 


~ 


AQAA AAOAAAMADOO0O74:0°30:3 


a 
* 


C* 


DAAAMNQAAD 
+ 


(ap) 
+ 


Cx* 


a 
* 


AIOOOAGD0A0OO00 0:0 


EVAL 
Fill in Signature Subsec 
EVAL 
EVAL 
EVAL 
EVAL 
EVAL 
EVAL 
Fill in private key name 
EVAL 
EVAL 
EVAL 


MOVEL 
Adjust token length 
EVAL 


MOVEL 
MOVE 
Z-ADD 


CALLP 


MOVEL 
EXSR 


** Build path name 


TOKENARRAY (INDEX +4) = X'OC' 
tion 

INDEX = INDEX + 12 
TOKENARRAY (INDEX +1) = X'45' 
TOKENARRAY (INDEX +3) = X'Q1' 
TOKENARRAY (INDEX +4) = X'48' 
TOKENARRAY (INDEX +5) = X'Q1' 
TOKENARRAY (INDEX +6) = X'O1' 


INDEX = INDEX + 6 

NAMEPTR1 = %ADDR(TOKENARRAY (INDEX +1)) 
NAMEPTR2 = 

%ADDR (TOKENARRAY (PRVSECLEN+PUBSECLEN+12+1) ) 
NAME2 NAME1 


LENGTH = INDEX + 64 + 258 
MSB TOKENARRAY (3) 
LSB TOKENARRAY (4) 
TOKENLEN = LENGTH 


"RETAIN ' RULEARRAY 
"CLONE RULEARRAY 
2 RULEARRAYCNT 


CSNDPKG (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
ZERO: 
REGENDATA: 
TOKENLEN: 
TOKEN: 
TRANSPORTKEK: 
GENKEYLEN: 
GENKEY) 


MSG (1) MSGTEXT 
RETURNCODE FAILRETC 
REASONCODE FAILRSNC 
"CSNDPKG' SAPI 
SNDMSG 


MSG(2) MSGTEXT 
SNDMSG 
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C EVAL PATHLEN = %LEN(%TRIM(KEYNAMEPARM) ) 
C PATHLEN SUBST KEYNAMEPARM: 1 PATH 

C EVAL %SUBST (PATH: PATHLEN+1:4) = '.PUB' 
C* 

Cx ** Open the file 

Cx* 

C EVAL FILED = open(PATH: OFLAG) 

(3 

Cx ** Check if open worked 

Cx* 

C FILED IFEQ -1 

C* 

Cx ** Open failed, send an error message 

Cx« 

C MOVEL MSG(3) MSGTEXT 

C EXSR SNDMSG 

C* 

C ELSE 

Cx* 

Cx ** Qpen worked, write certificate out to file and close file 
C* 

C CALLP write (FILED: 

C GENKEY: 

C GENKEYLEN) 

C CALLP close (FILED) 

C* 

Cx ** Send completion message 

C* 

C MOVEL MSG(4) MSGTEXT 

C EVAL %SUBST (MSGTEXT: 32: PATHLEN + 4) = 
C %SUBST(PATH: 1: PATHLEN + 4) 
C EXSR SNDMSG 

C ENDIF 

Cx* 

C SETON LR 
Cx* 


CR KKK KKK EK KKK KEKE KR EKER KERR ERE RK RK ER KERR EKER ER ERE RR EK ERE RK EKER 


Cx Subroutine to send a message 
CR KKK KKK EK KKK KEKE KKK KEK KKK ERE KK RK EK KEK KKK KKK EKER KERR EK ERE RR EKER EK 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


** 

CSNDPKB failed with return/reason codes 9999/9999. 
The retained key was successfully created. 

The file could not be opened. 

The certificate was written to 


Example: ILE C program for registering a public key hash 
Change this program example to suit your needs for registering a hash of a public 
key certificate. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


210 iSeries: Cryptographic hardware 


/* REGHASH 


/* Sample program to register the hash of a CCA public key 
/* certificate. 


/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 


/* This material contains programming source code for your 

/* consideration. These examples have not been thoroughly 

/* tested under all conditions. IBM, therefore, cannot 

/* guarantee or imply reliability, serviceability, or function 
/* of these program. All programs contained herein are 

/* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
/* these programs and files. 

/* 

/* 

/* Note: Input format is more fully described in Chapter 2 of 

/* IBM 4758 CCA Basic Services Reference and Guide 

/* (SC31-8609) publication. 

/* 


/* Parameters: Stream file containing public key certificate 


/* 

/* Example: 

/* CALL PGM(REGHASH) PARM(CERTFILE) 

/* 

/* 

/* Note: This program assumes the card with the profile is 
/* already identified either by defaulting to the CRPO1 
/* device or by being explicitly named using the 

/* Cryptographic_Resource_ Allocate verb. Also this 

/* device must be varied on and you must be authorized 
/* to use this device description. 

/* 


/* The Common Cryptographic Architecture (CCA) verbs used are 
/* PKA _Public_Key Hash Register (CSNDPKH) and One Way Hash WH). 
/* (CSNBOWH) . 


/* Use these commands to compile this program on iSeries: 
/* ADDLIBLE LIB(QCCA) 


/* CRTCMOD MODULE(REGHASH) SRCFILE(SAMPLE) 

/* CRTPGM PGM(REGHASH) MODULE (REGHASH) 

/* BNDDIR(QCCA/QC6BNDDIR) 

/* 

/* Note: Authority to the CSNDPKH and CSNBOWH service programs 

/* in the QCCA library is assumed. 

/* 

PR eecieevoesueteesesb eee eeetee sheds te teu bouton Sect eoe eee eetot eee 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 


int main(int argc, char *argv[]) 


| Pree eesheee esse amSarseSses See eense see ese neesescee sees aaa sececeses ces 
long return_code = Q; 

long reason_code = Q; 

long exit_data_length = 0; 

char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 
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long chaining_vector_length = 128; 
long hash_length = 20; 

long text_length; 

unsigned char chaining _vector[128]; 
unsigned char hash[20] ; 


| ee eee Oe ee ee */ 
/* Declares for working with a PKA token x/ 
| Peeeeeeesssesseseseeeesee esses eee seta sae seeeeeeeae see senescees es */ 
long pub_sec_len; /* Public section length x/ 
long cert_sec_len; /* Certificate section length */ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
char name[64]; /* Registered key name x/ 
long count; /* Number of bytes read from file */ 
FILE «fp; /* File pointer x/ 
if (argc < 2) /* Check the number of parameters passed */ 


printf("Need to enter a public key name\n"); 


return 1; 
} 
memset(name,' ',64); /* Copy key name (and pad) to a 64 byte *«/ 
/* field. */ 
memcpy (name, argv[1],strlen(argv[1])); 
fp = fopen(argv[1],"rb"); /* Open the file for reading */ 
if (!fp) 
{ 
printf("File %s not found.\n",argv[1]); 
return 1; 
} 
memset (token,0,2500) ; /* Initialize the token to 0 */ 
count = fread(token,1,2500,fp); /* Read the token from the file */ 
fclose(fp); /* Close the file */ 
/* Determine length of token from length */ 
/* bytes at offset 2 and 3. */ 
token_len = ((256 * token[2]) + token[3]); 
if (count < token_len) /* Check if whole token was read in */ 
{ 
printf("Incomplete token in file\n"); 
return 1; 


} 


[RRR KKK A KKK KKK K KKK KKK KKK IK KKK AK KIRKE AK KEK KIER AKER A KKK | 


/* Find the certificate offset in the token */ 
/* x/ 
/* The layout of the token is */ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes */ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x/ 
/* x/ 


[RRR KKK KKK A KKK AK KKK KEK KK KKK KKK AK KAKA KKK KIER AKER A KKK | 


pub_sec_len = ((256 * token[10]) + token[11]); 
offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate section x/ 
/* length from the length bytes at */ 


/* offset 2 of the section. */ 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 
tempOffset = offset + 4; /* Set offset to first subsection */ 
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/* Parse each subsection of the certificate until the */ 
/* signature subsection is found or the end is reached.*/ 
/* (Identifier for signature subsection is Hex 45.) */ 


while(token[tempOffset] != 0x45 && 
tempOffset < offset + cert_sec_len) 
{ 


tempOffset += 256 * token[tempOffset + 2] + token[tempOffset+3] ; 


Da eee ee ee ee ee */ 
/* Check if no signature was found before the end of */ 
/* the certificate section. */ 
[Reee= Seeseee esas sos ease eee oe Sessa see eae ee eeedee sees «/ 


if (token[tempOffset] != 0x45) 


printf("Invalid certificate\n"); 
return 1; 


} 


[ERK K ERA KERA KKK KKK KKK KKK KKK RK KKK IKKE KKK A KIER AKER AKER KKK | 

/* Hash the certificate */ 

[RRR KER A KKK A KKK KKK KKK KK EIR KKK KEI KKEKKKE A KKK AKER AKER KKK | 

text_length = tempOffset - offset + 70; /* Text length is length ¥*/ 
/* of certificate subsection. */ 


memcpy ((void*)rule_array,"SHA-1 ",8); /* Set rule array */ 
rule_array_count = 1; 

chaining_vector_length = 128; 

hash_length = 20; 


CSNBOWH( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&text_length, 
&token[offset], 
&chaining_vector_length, 
chaining_vector, 
&hash_length, 
hash) ; 


if (return_code != Q) 
printf("One Way_Hash Failed : return reason %d/%d\n", 


return_code, reason_code) ; 
return 1; 


} 


[RRR KER AKER A KKK AK KKK KKK KK AK KKK KKK A KKK KK AK KEK KKK AKER KKK | 


/* Register the Hash */ 
[RRR K ERA K RRA K ERIK REA KKEK KEIR KEK KKK IKEA IKEA KEKE AKER KKK | 
/* Set the rule array x/ 


memcpy((void*)rule_array,"SHA-1 CLONE ",16); 
rule_array_count = 2; 
/* Build the name of the retained */ 
/* key from the file and "RETAINED"*/ 
memcpy (&name[strlen(argv[1])],".RETAINED",9) ; 


CSNDPKH( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
name, 
&hash_length, 
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hash) ; 
if (return_code != 0) 


printf("Public Key Register_Hash Failed : return reason %d/%d\n", 
return_code, reason_code) ; 
return 1; 


} 


name[strlen(argv[1]) + 9] = 0; /* Convert name to a string */ 
printf("Hash registered for %s.\n",name) ; 


} 
Example: ILE RPG program for registering a public key hash 


Change this program example to suit your needs for registering a hash of a public 
key certificate. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


DARK R KKK KKK KK ER KKK EK KKK ERK KKK KEK KKK RRR KKK KK KEKE RRR RRR KERR ERR RK REK 
D* REGHASH 

Dx« 

D* Sample program to register the hash of a CCA public key 

D* certificate. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
D* IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

Dx Parameters: Stream file containing public key certificate 
Dx« 

D* Example: 

D* CALL PGM(REGHASH) PARM(CERTFILE) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(REGHASH) SRCFILE(SAMPLE) 
D* CRTPGM PGM(REGHASH) MODULE (REGHASH) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSNDPKH and CSNBOWH service programs 
Dx in the QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* PKA Public_Key_Hash Register (CSNDPKH) and One_Way_Hash 
C* (CSNBOWH) . 


* 

Basco eeaschicceieegitsk cine 
PeeceeesosescccceeceescesecscesS see ce ese eee cesceescecesce 

D* Declare variables used by CCA SAPI calls 

Peeeeee sree teseee ees esee sesso eesee see esse ee estes eeesee 

Dx ** Return code 
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DRETURNCODE 
Dx« 
DREASONCODE 
Dx 
DEXITDATALEN 
Dx 
DEXITDATA 
Dx 
DRULEARRAYCNT 
Dx« 
DRULEARRAY 
Dx 
DTOKENLEN 
Dx 

DTOKEN 
DTOKENARRAY 
Dx« 
DCHAINVCTLEN 
Dx« 
DCHAINVCT 
Dx 

DHASHLEN 

Dx« 

DHASH 

Dx 
DTXTLENGTH 
Dx 

DNAME 

Dx« 

Dx 
DLENSTRUCT 
DMSB 

DLSB 
DLENGTH 

Dx« 

Dx 
DCRTSECLEN 
Dx 
DPUBSECLEN 
Dx« 
DTKNINDEX 
Dx« 
DTMPINDEX 
Dx« 

DFILED 

Dx 

DPATH 
DPATHLEN 

Dx« 

DOFLAG 

D« 


9B 0 
Reason code 
9B 0 
Exit data length 
9B 0 
Exit data 
4 
Rule array count 
9B 0 
Rule array 
16 
Token length 
9B 0 INZ(2500) 
Token and array for subscripting token 
2500 
1 DIM(2500) 
Chaining vector length 
9B 0 INZ(128) 
Chaining vector 
128 
Hash length 
9B 0 INZ(20) 
Hash 
20 
Text length 
9B 0 
Name of retained key 
64 
Structure used for aligning 2 bytes into a 
2 byte integer. 


2 
1 1 
2 2 
1 2B 0 
Certificate section length 
9B 0 
Public key section length 
9B 0 
Index into PKA key token 
9B 0 
Index into PKA key token 
9B 0 
File descriptor 
9B 0 


File path and path length 
80 INZ(*ALLX'00') 
9B 0 
Open Flag - Open for Read only 
101 0 INZ(1) 


DA RRRKKKKK KK KEK KKK KK KKK ERK KEK KE KKK KR KEK KERR KK KR ER KEK KERR KR ERERE 


D* Prototype for PKA Public_Key_ Hash Register (CSNDPKH) 


DA KRKKKKKKKK KER KKK KKK KK ERK KER KERR KERR RRR RRR RR RER RRR ERK KR ERERER 


DCSNDPKH 
DRETCOD 
DRSNCOD 
DEXTDTALN 
DEXTDT 
DRARRYCT 
DRARRY 
DKYNAM 
DHSHL 
DHSH 

Dx« 


PR 


20 OPTIONS (*VARSIZE) 


DA RRA KK KKK KK KEK KK KEK KKK RRR KKK KKK KK RRR RRR KEK KER ER RK KERR KR ERERK 


D* Prototype for One Way Hash (CSNBOWH) 
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DARK RKKKKKKK KER KK KEK KKK KKK KKK KEK KKK RRR KERR KK KR ERR KR RKR KK RERE KK 


DCSNBOWH PR 

DRETCOD 9B 0 
DRSNCOD 9B 0 
DEXTDTALN 9B 0 
DEXTDT 4 
DRARRYCT 9B 0 
DRARRY 16 
DTXTLEN 9B 0 
DTXT 500 OPTIONS (*VARSIZE) 
DCHNVCTLEN 9B 0 
DCHNVCT 128 
DHSHLEN 9B 0 
DHSH 20 

Dx« 

Dx« 


DA RRR KKK KKK KK ERK KEKE KKK KERR RRR KERR KERR ER KERR KER RR ER RRR ER KER REERREEK 


D* Prototype for open() 


DARK R KKK KKK KK ER KK KKK KKK KKK KKK EKER KEKE RK KERR KKK KER EKER KK RERERK 
Dx value returned = file descriptor (OK), -1 (error) 
Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

D* Open flags 

D 9B @ VALUE 

D« (OPTIONAL) mode - access rights 

D 10U @ VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U 0 VALUE OPTIONS (*NOPASS) 
Dx« 

DARK KKK KKK KK ERK KK KEK K KK ER KEKE RRR KERR KKK ERK RRR RRR REE RRR RRR KERR RR RRREKE RRR 
D* Prototype for read() 

DARK KK KK KKK KK ER KK KEK KKK KKK KKK KEK K RRR KEK KERR KEK KR ERE RRR KEKE RRR KEK 
Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
D« File descriptor returned from open() 

D 9B @ VALUE 

D* Input buffer 

D 2500 OPTIONS (*VARSIZE) 
D* Length of data to be read 

D 9B @ VALUE 

Dx« 


DA RRR KKK KKK KK KEKR KKK KEK KKK ERK KERR KK KERR KK ERK RRR KKK KERR KERR KK KERR RRRKE RRR 
D* Prototype for close() 

DARK KK KKK KKK KER KKK ERK KEKE RK RRR KR ERR KK ER KR RRR RRR EER KER RR KR RRR RERRERERER 
Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

Pesce bet see ee eee eee eee ee eee eee See eee eee See eee eee 
Dx **x Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

Peeseseccsseee cee cee Stee e eee Seer cee ec ee ee eee eee eee oe ee eece 
DMSG S 75 DIM(6) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 80 

DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ") 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* 2, 
DSTACKCOUNTER S 9B 0 INZ(2) 
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DERRCODE DS 


DBYTESIN 1 4B 0 INZ(O) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 

CR KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KERR KERR KERR KEK KR KERR ERERERERE 
Cx START OF PROGRAM * 
Cx * 
C *ENTRY PLIST 

¢ PARM FILEPARM 50 


CR KKK KKK KKK KKK KEK RK KEK KKK ERK KK EKER KEK KEK KERR ER ERK RR ERE KKK ERR ERE 


Cx Open certificate file 
CR KKK KK KK KKK KKK KKK RK KER KEK ERK KK RK EKER KEKE RR EKR ERR RR ERE REE ERR 


Cx* ee ne ar * 

Cx  »** Build path name * 

Cx ee * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx* I i cn nto asl * 

Cx »* Open the file * 

Cx« eceeseseese=asesseees * 

C EVAL FILED = open(PATH: OFLAG) 
Cx Hesederesnenesseseesses * 

Cx  »* Check if open worked « 

Cx Heseweeseeescee seuss cees * 

C FILED IFEQ -1 

Cx Aiea se ee ee este ee eee eee eS eee eS * 

Cx * Open failed, send an error message * 

Cx« tweseccesaaesaceecssssseSsoeesaceseas== * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx« 

C ENDIF 

Cx« tiaceacesaseaS esse osoosese sees asecetececesecosSseeses * 
Cx * Open worked, read certificate and close the file * 
Cx Kemet ees sc ee oe tSse Ske eee eee eee eee sesso ee eS * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx« 

C* i a ss i Sere ees elo * 

Cx * Check if read operation was OK * 

Cx« Lc Sse cece R oes ee on SooeSeeetalsaesse * 

C TOKENLEN IFEQ -1 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 

Cx* Sipe cet Sea eee ame ae a eee a eee miele * 

Cx * Check if certificate length is valid * 

Cx * The length bytes start at position 3 * 

Ce esse loessoee ese sslesesceoe eee ssesle sce * 

C EVAL MSB = TOKENARRAY (3) 

C EVAL LSB = TOKENARRAY (4) 

C LENGTH IFLT TOKENLEN 

Cx« keewecaeceeeseasosecesseSseeseecsese * 

Cx * Certificate length is not valid * 

Cx« keeecceeeseeseecoesscsesesseeeesceses * 

C MOVEL MSG (3) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 


CR KKK KK KKK KKK KEKE KR KK ERK ER ERK KK RK EKER KEK ERR ER ERR RR ERE REE ERRERE 
Cx Find the certificate in the token 

Cx« 

Cx The layout of the token is 
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Cx* 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at position 3 (11 overall) 
Cx - Private key name - 68 bytes 

Cx - Certificate section 

Cx* 

Cx Note: 1 is added because RPG arrays start at 1. 

CR KKK KK KK EK KKK KKK KK EKER KERR ER ERK RK ERE RR EK ERR ER ERE RR EK ERE RR ERERREE 


C EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
C* 

Cx* VeseescacastenseseesSscseseoesésoceoseeceess * 

Cx * Determine length of certificate section * 

Cx * Length bytes are at position 2 of the * 

Cx * section. 

C* a oe a a a a pace * 

C EVAL MSB = TOKENARRAY(TKNINDEX + 2) 

C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 

¢ EVAL CRTSECLEN = LENGTH 

C EVAL TMPINDEX = TKNINDEX + 4 

Cx* 

Cx* Lassoacasoasosseonaescuees soos ceeoseesseSeaeeseceaceses * 
Cx * Parse each subsection of the certificate until the * 
Cx * signature subsection is found or the end is reached.* 
Cx * (Identifier for signature subsection is Hex 45.) * 
C* toc Seseoseecses seer assess oesesesecseSsesseecessosseessees * 
C DOW (TOKENARRAY (TMPINDEX) <> X'45') AND 
C (TMPINDEX < TKNINDEX + CRTSECLEN) 
C EVAL MSB = TOKENARRAY(TMPINDEX + 2) 

C EVAL LSB = TOKENARRAY(TMPINDEX + 3) 

C TMPINDEX ADD LENGTH TMPINDEX 

C ENDDO 

C* 

C* (osc acan sae aoe eee eee ace e See eee eee cee eee * 
Cx * Check if no signature was found before the end of * 
Cx * the certificate section. * 
Cx* asesalasessosschoces cee eseoaecece a caseeeoseeseeeecuce * 
C IF TOKENARRAY (TMPINDEX) <> X'45' 

C MOVEL MSG(4) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

C* 


CR KKK KKK KEK KKK KEKE KR EKER KEK EKER KKK EKER KER ERR ER ERK RR EK ERE RR EKER 


Cx Hash the certificate 
CR KKK KKK KKK KK KKK KKK KEK KKK ERE KK RK EK KEK KEK KERR EK ERK RR EK ERE RR EKER 


Cx Rese se eeeeessee ose ese ecese eee stesso eee ees * 

Cx »* Calculate the length to hash * 

C* I ss a ni at * 

Cc EVAL TXTLENGTH = TMPINDEX - TKNINDEX + 70 
Cx* teseeeeseesee sees sees eecsaseencecencSeeses * 

Cx »* Set the keywords in the rule array * 

C* encccca So osessece a Sceemeecnt case eee eee eee * 

C MOVEL "SHA-1 : RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 
Cx ee * 

Cx »* Call One Way Hash SAPI * 

Cx Pessonsusssusssssresescees * 

C CALLP CSNBOWH (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C TXTLENGTH: 
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¢ TOKENARRAY (TKNINDEX) : 
C CHAINVCTLEN: 
C CHAINVCT: 

C HASHLEN: 

C HASH) 

Cx! Fesecsssssessceecssecssce * 

Cx * Check the return code * 

Ck, #iseeeseseceetoceussessee * 

C RETURNCODE IFGT 0 

Cx Resssoscsscssssscccsacss * 

Cx * Send failure message * 

Cx« Resesseessetsesseseecess * 

¢ MOVEL MSG(5) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

¢ MOVEL "CSNBOWH' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 


CR K KK KK KK KKK KKK KKK RK K ERK ER ERK KK RK EKER KEK ERR ERE RRR ERE REE ERR ERE 


Cx Register the certificate hash 
CK KK KKK KKK KKK KR KKK KEK KEK ERK KK KK ER KERR RK KERR ERE KK RR ER ERK ERRERE 


Cx« Fis soacsacesacuessusesSscessceoususseecccosces * 

Cx »* Set the keywords in the rule array * 

Cx* Gs ip oy a i a i a fs * 

C MOVEL "SHA-1 ' RULEARRAY 

C MOVE "CLONE! RULEARRAY 

C Z-ADD Z RULEARRAYCNT 
Cx« Mecsas sees eeeoeasancceeceeeeeoeeseecessees * 

C* »* Build the key name (FILENAME.RETAINED) * 

Cx* Se | pn 8 esa is omc ceo i ns es * 

C EVAL %SUBST(NAME: 1: PATHLEN) = 
C %SUBST (PATH: 1: PATHLEN) 
¢ EVAL %SUBST (NAME: PATHLEN+1:9) = '.RETAINED' 
Cx* SF ce yi no le i et erm tee * 

Cx * Call PKA Public Key Hash Register * 

Cx« tooonee see saceecuseansececceoresasee * 

C CALLP CSNDPKH (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C NAME: 

C HASHLEN: 

C HASH) 

Ck #teesesesecseececeeseecee * 

Cx »* Check the return code * 

Ck “Fees eeee eee seeee cele ce ses * 

C RETURNCODE IFGT 0 

Cx« esse ecesonesass=essesee * 

Cx * Send failure message * 

Cx* scan Saaaoeaeaaeeacoees * 

C MOVEL MSG (5) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNDPKH' SAPI 

C EXSR SNDMSG 

C ELSE 

Cx« tWaisonca Seeen cee ee ase: * 

Cx * Send success message * 

Cx* SLinscsee cece as kee sees se * 

¢ MOVEL MSG (6) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 41: PATHLEN + 9) = 
C %SUBST (NAME: 1: PATHLEN + 9) 
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C EXSR SNDMSG 


C ENDIF 

Ce 

C SETON LR 
C* 


CR KKK KKK KEK KKK KK KERR KK ERK KEK ERE KK RK ER KEK KKK KERR EKER KERR EKER ERK EKER EK 


Cx Subroutine to send a message 
CR KKK KKK KEK KKK KKK KKK KEKE EKER ERK KEKE KERR EK ERR ER ERR RR EK ERE RR EKER 


C SNDMSG BEGSR 

C CALL "QMHSNDPM ' 

Cc PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


* 

The file could not be opened. 

There was an error reading from the file. 

The length of the certificate is not valid. 

The certificate is not valid. 

CSNBOWH failed with return/reason codes 9999/9999. 
The hash was successfully registered as 


Example: ILE C program for registering a public key certificate 
Change this program example to suit your needs for registering a public key 
certificate. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


| PossenSenesSsssesseus seuesesadsacssesesss sSsseeeosesashSscusedsceea= */ 
/* REGPUBKEY x/ 
/* x/ 
/* Sample program to register a CCA public key certificate x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x*/ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: Stream file containing public key certificate */ 
/* x/ 
/* Example: */ 
/* CALL PGM(REGPUBKEY) PARM(CERTFILE) */ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 


220 iSeries: Cryptographic hardware 


/* device must be varied on and you must be authorized */ 


/* to use this device description. */ 
/* x*/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* PKA_Public_Key Register (CSNDPKR). x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(REGPUBKEY) SRCFILE(SAMPLE) x/ 
/* CRTPGM PGM(REGPUBKEY) MODULE(REGPUBKEY) */ 
/* BNDDIR(QCCA/QC6BNDDIR) x/ 
/* x/ 
/* Note: Authority to the CSNDPKR service program */ 
/* in the QCCA library is assumed. */ 
/* x/ 
[RoseeSeeeeseseee ses Sects le ee eee setae see ees ee ae cee caeSeee eee «/ 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 


int main(int argc, char *argv[]) 


| eee eee ate se See ae eee ee */ 
/* Declares for CCA parameters */ 
| ee ee eee ee ee ee See ee eee eee ee ee */ 


long return_code = Q; 

long reason_code = Q; 

long exit_data_length = 0; 
char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 
long token_len = 2500; 
char token[2500]; 


/Reenssescesesesseceseesas see cssetessesssssssscesetssessssesseSe seas */ 
/* Declares for working with a PKA token x/ 
[#eees See esee Ses Ses eeh el enss oe See ates ss etee ee et Secs soe ce seeete eee */ 
long pub_sec_len; /* Public section length */ 
long cert_sec_len; /* Certificate section length */ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
char name[64] ; /* Registered key name x/ 
long count; /* Number of bytes read from file */ 
FILE «fp; /* File pointer x/ 
if (argc < 2) /* Check the number of parameters passed */ 


printf("Need to enter a public key name\n"); 


return 1; 

} 
memset(name,' ',64); /* Copy key name (and pad) to a 64 byte */ 

/* field. */ 

memcpy (name, argv[1],strlen(argv[1])); 
fp = fopen(argv[1],"rb"); /* Open the file for reading */ 
if (!fp) 

{ 

printf("File %s not found.\n",argv[1]); 

return 1; 

} 
memset (token,0,2500) ; /* Initialize the token to 0 */ 
count = fread(token,1,2500,fp); /* Read the token from the file */ 
fclose(fp); /* Close the file */ 


/* Determine length of token from length */ 
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/* bytes at offset 2 and 3. x/ 
token_len = ((256 * token[2]) + token[3]); 
if (count < token_len) /* Check if whole token was read in */ 


printf("Incomplete token in file\n"); 
return 1; 


} 


[RRR KKK KKK KKK KKK A KKK KK AKKK KKK IKK KA KK EK KKK AKER AKER KK | 


/* Find the certificate length in the token x/ 
/* */ 
/* The layout of the token is */ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 2 x*/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x*/ 


[KERR KERR KER AKER AKER A KEKE IKKE AK KEI KK AKK EAA KEKE AKER EK | 


pub_sec_len = ((256 * token[10]) + token[11]); 

offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 
/* Determine certificate section */ 
/* length from the length bytes at »*/ 
/* offset 2 of the section. */ 

cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 


[BRR RKKR KKK A KKK KKK KKK KKK IK KKK IKK AKKKAKKEA KKK AKER AK KERK KE | 


/* Register the Public Key */ 
[RRR KKK AKER IKKE A KKK KKK KKK IK KKK KKK A KKK IKKE A KKK AKER KKK ERK KE | 
memcpy((void*)rule_array,"CLONE ",8); /* Set rule array */ 


rule_array_count = 1; 
/* Build the name of the retained */ 
/* key from the file and "RETAINED"*/ 
memcpy (&name[strlen(argv[1])],".RETAINED",9); 


CSNDPKR( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
name, 
&cert_sec_len, 
&token[offset]); 


if (return_code != Q) 


printf("Public Key Register Failed : return reason %d/%d\n", 
return_code, reason_code); 
return 1; 


} 


name[strlen(argv[1]) + 9] = 0; /* Convert name to a string */ 
printf("Public key registered for %s.\n",name) ; 


} 


Example: ILE RPG program for registering a public key 
certificate 

Change this program example to suit your needs for registering a public key 
certificate. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


Do III IO IOI IO IO IO IOI IO GI IOI II I IR IR Ie 
D* REGPUBKEY 
Dx« 
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Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 


Sample program to register a CCA public key 
certificate. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these programs. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 

Parameters: Stream file containing public key certificate 


Example: 
CALL PGM(REGPUBKEY) PARM(CERTFILE) 


Use these commands to compile this program on iSeries: 


D* CRTRPGMOD MODULE(REGPUBKEY) SRCFILE(SAMPLE) 

D* CRTPGM PGM(REGPUBKEY) MODULE (REGPUBKEY) 

Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSNDPKR service program 

Dx in the QCCA library is assumed. 

Dx« 

D* The Common Cryptographic Architecture (CCA) verbs used are 
D* PKA Public _Key Register (CSNDPKR). 

Dx« 

DAKAR K KKK KKK KEK KKK KKK KK ERK KEK KERR KK RRR RRR KKK KER KEK RRR RRR EERE 
DeeeeccsossessceecesseeS esses Sse ce ssoascossossseSScScessse 
Dx Declare variables used by CCA SAPI calls 

Dxeee eee se eee sce esses cee ease Sea ee se eee eee ee See 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITTDATALEN S 9B 0 

Dx xx Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Token length 

DTOKENLEN S 9B 0 INZ(2500) 

D* ** Token and array for subscripting token 
DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

Dx ** Name of retained key 

DNAME S 64 

D* xx Structure used for aligning 2 bytes into a 
Dx xx 2 byte integer. 

DLENSTRUCT DS 2 

DMSB 1 if 

DLSB 2 2 

DLENGTH 1 2B 0 

Dx xx Certificate section length 
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DCRTSECLEN S 9B 0 


Dx ** Public key section length 
DPUBSECLEN S 9B 0 

Dx ** Index into PKA key token 
DTKNINDEX S 9B 0 

Dx ** Index into PKA key token 
DTMPINDEX S 9B 0 

D* ** File descriptor 

DFILED S 9B 0 

D« ** File path and path length 
DPATH S 80 INZ(*ALLX'00') 
DPATHLEN S 9B 0 

D* ** Open Flag - Open for Read only 
DOFLAG S 101 @ INZ(1) 

Dx« 


DAKAR KKK KKK KK ERK KEKE KKK KERR KKK ERK RRR RR KER KERR RRR RR ER KEK RERERE 


D* Prototype for PKA Public Key Register (CSNDPKR) 


DA RRKKKKK KKK KER KKK ERK KK ERK KERR RRR KERR ER KERR KER RR ER ERR ERK RERREERK 


DCSNDPKR PR 

DRETCOD 9B 0 

DRSNCOD 9B 0 

DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DKYNAM 64 

DCRTLEN 9B 0 

DCRT 500 OPTIONS (*VARSIZE) 

Dx« 

DARK RKKKKK KK KER KKK KEK KKK KKK KKK KEK KKK RRR KKK KEK KR ERR KERR KK REE 
D* Prototype for open() 

DA RRR KKK KKK KK ERK KEKE KKK KERR KKK RRR KERR ER KERR KERR RRR RRR ER KER RERRREEK 
D« value returned = file descriptor (OK), -1 (error) 
Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

D* Open flags 

D 9B @ VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U © VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 


DA RRA KAKA KKK ERK KEKE KKK KER KKK RRR KK ERK KK ERK RRR KK RK RRR RRR KERR KERR RR RKER KKK 


D* Prototype for read() 


DARK R KKK KKK KK ERK KK RK KK KERR KERR KK KR ERR KER KEK RR ER ERR ERK RERREEK 
Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
D« File descriptor returned from open() 

D 9B @ VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
D* Length of data to be read 

D 9B @ VALUE 

Dx« 


DA RRRKKKKKKK KER KKK EK K KK KKK KK RR KKK ERK KK ERK RRR KK KK RR KK KERR KK KERR RRERKE KERR 
D* Prototype for close() 

DARK KKKKKKKK KER KKK KEK KKK ERK KK RRR KKK KKK KER KR KER KERR ERK KR RR KK KERR RERKEKR KERR 
Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

P¥essseeescese ete e ese eee eee eee Sse ee cee ee See eee eee secs 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Peeeeeessess ccs ceecee cc csc ssc eeeee ecco sees cosscese sec ceceeces] 
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DMSG S 75 DIM(5) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 ‘INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(! ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY Ss 10 INZ('* 1) 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(Q) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 

CRRA KKK AK KKK KKK KK KKK KKK KKK RRR ER KR ER ERE RRR ERE RR ERR ER ERE RERE REE 
Cx START OF PROGRAM * 
Cx« * 
C *ENTRY PLIST 

C PARM FILEPARM 50 


CR KKK KKK KKK KK KKK KR EKER KER ERE KK EKER KER KEKE RR EK ERR RR ERE REE ERRERE 


Cx Open certificate file 
CR KKK KKK KKK KK KKK KR KEKE KK KEK ERK KK EKER KERR RK EKER ER ERK ERRERE 


Cx Berean swear sees eee * 

Cx  »** Build path name * 

Cx *esenssessenescesessss * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx« Veceuseseaseaasossacee * 

Cx »* Open the file * 

Cx kesSssteaeocessesesee * 

C EVAL FILED = open(PATH: OFLAG) 

(e eee * 

Cx  »* Check if open worked * 

Cx Pseseeessseteseeseeee es * 

C FILED IFEQ -1 

Cx eases l sesso ssesss—Ssesseoseeesso==—== * 

Cx * Open failed, send an error message * 

Cx* a a a, cn ee el en * 

C MOVEL MSG (1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx« 

C ENDIF 

Cx* SI si a a li a aw et ee * 
Cx * Open worked, read certificate and close the file * 
Cx« oecieccsonceaces cesses Secs eeee sees eaeseceecceesS * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx 

Ce Kessel osssoseeeselessssceoceeeasesaesse * 

Cx * Check if read operation was OK * 

Cx MipeetetoecSsiseeese see eee eee eee See * 

C TOKENLEN IFEQ -1 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 

Cx esate eseassaSoasseosesseseoesesasseo * 

Cx * Check if certificate length is valid * 

Cx * The length bytes start at position 3 * 

Cx* Se ys a ro ee sr ee et ties * 

C EVAL MSB = TOKENARRAY (3) 

C EVAL LSB = TOKENARRAY (4) 

C LENGTH IFLT TOKENLEN 
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Cx 


Kee eee * 

* Certificate length is not valid * 

Kee eee ee * 
MOVEL MSG (3) MSGTEXT 
EXSR SNDMSG 
RETURN 
ENDIF 


CR KKK KKK EK KKK KEKE KKK KEKE KK ERE KK RK ER KEK KKK KEKE ERK RR EK ERE RK EKER 


Cx Find the certificate in the token 

Cx* 

Cx The layout of the token is 

C* 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at position 3 (11 overall) 
Cx - Private key name - 68 bytes 

Cx - Certificate section 

C* 

Cx Note: 1 is added because RPG arrays start at 1. 

CR KKK KKK KEK KKK KKK KR KK ERK KK EKER KKK ER KEK KKK KERR EK ERE RR EK ERE RR EKER EK 
Cc EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
Cx* 

C* at i a a so a * 

Cx * Determine length of certificate section * 

Cx * Length bytes are at position 2 of the * 

Cx * section. 

C* eae eeeeee ae escSee eee eee Sees sees seeecesee * 

Cc EVAL MSB = TOKENARRAY(TKNINDEX + 2) 

C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 

C EVAL CRTSECLEN = LENGTH 

Cx* 


CR KKK KKK KEK KKK KK EK KKK ERK EKER ERK RK EKER KEK ERR ER ERE RR E KERR RR EKER 


Cx Register the public key 


CR KKK KKK KEK KKK KEKE KKK KEKE ER ERE RK RK ERK RR EKER KER EKER EK ERE RR EKER 


Cx« 
Cx* 
C* 
C 

C 

C* 
Cx* 
C* 


(<gp 1S cap Jay app in sep Yn op Tak <a Ya a Ja ap is app We cep <a Ta a Ta pe ae We cep ae I I a} 
+ + FF + 


Kee ee * 
* Set the keywords in the rule array * 
Kee eee ee * 
MOVEL "CLONE '' RULEARRAY 
Z-ADD 1 RULEARRAYCNT 
Kee ee * 
* Build the key name (FILENAME.RETAINED) * 
Kee eee * 
EVAL %SUBST(NAME: 1: PATHLEN) = 
%SUBST (PATH: 1: PATHLEN) 
EVAL %SUBST (NAME: PATHLEN+1:9) = '.RETAINED' 
Kee ee * 
* Call PKA Public Key Register * 
Kee ee * 
CALLP CSNDPKR (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
NAME: 
CRTSECLEN: 
TOKENARRAY (TKNINDEX) ) 
Kee ----- * 
* Check the return code * 
Kee ee - - - - - - - - - - * 
RETURNCODE IFGT 0 
Kee ee * 


* Send failure message * 


iSeries: Cryptographic hardware 


**k 
Th 
Th 
Th 
CS 
Th 


Cx« De ee eee * 

C MOVEL MSG(4) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

C ELSE 

Cx* Secs sa nana cane eoaeom ae * 

Cx * Send success message * 

Cx« tJicsssssccuncuesaoacess * 

C MOVEL MSG(5) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 41: PATHLEN + 9) = 
C %SUBST (NAME: 1: PATHLEN + 9) 
C EXSR SNDMSG 

C ENDIF 

Cx« 

€ SETON LR 


CR KKK KK KEKE KKK KE KKK KKK ERK ER ERE KK RK EKER KEK ERR EKER REE ERE RRR ERR ERE 


Cx Subroutine to send a message 
CR KKK KKK KKK KK KKK KR KK ERK KK ERK KK EKER RE KK EKER ERE RK RR ER EKER ERR ERE 


C SNDMSG BEGSR 


C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


e file could not be opened. 

ere was an error reading from the file. 

e length of the certificate is not valid. 

NDPKR failed with return/reason codes 9999/9999. 
e hash was successfully registered as 


Example: ILE C program for certifying a public key token 


Change this program example to suit your needs for certifying a public key token. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


important legal information. 


ee ee ee a a ee */ 
CERTKEY x/ 
x/ 

Sample program to certify a CCA public key certificate to be x/ 
used for master key cloning. x/ 
* 

/ 

COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
* 

/ 

This material contains programming source code for your x/ 
consideration. These examples have not been thoroughly */ 
tested under all conditions. IBM, therefore, cannot */ 
guarantee or imply reliability, serviceability, or function x*/ 
of these program. All programs contained herein are x/ 
provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
these programs and files. x/ 
x/ 

x/ 

Note: Input format is more fully described in Chapter 2 of */ 
IBM 4758 CCA Basic Services Reference and Guide x/ 
(SC31-8609) publication. */ 
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/* 

/* Parameters: FILENAME - File containing public key token 
/* RETAINED_KEY_NAME - Name of key to certify token 
/* 

/* Example: 

/* CALL PGM(CERTKEY) PARM(MYKEY.PUB CERTKEY) 

/* 

/* 

/* Note: This program assumes the card with the profile is 

/* already identified either by defaulting to the CRPO1 
/* device or by being explicitly named using the 

/* Cryptographic_Resource Allocate verb. Also this 

/* device must be varied on and you must be authorized 

/* to use this device description. 

/* 


/* The Common Cryptographic Architecture (CCA) verbs used are 


/* Digital_Signature Generate (CSNDDSG) and One Way Hash (CSNBOWH) . 


/* 

/* Use these commands to compile this program on iSeries: 
/* ADDLIBLE LIB(QCCA) 

/* CRTCMOD MODULE(CERTKEY) SRCFILE(SAMPLE) 

/* CRTPGM PGM(CERTKEY) MODULE(CERTKEY) 


/* BNDDIR(QCCA/QC6BNDDIR) 

/* 

/* Note: Authority to the CSNDDSG and CSNBOWH service programs 

/* in the QCCA library is assumed. 

/* 

Paden Sesenes ses esacs scare oases] =ssecseesa=s—eoeeseee=se——s-—-s5555 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 
#include "decimal.h" 


extern void QDCXLATE(decimal(5,0), char *, char*, char *); 
#pragma linkage (QDCXLATE, OS, nowiden) 


int main(int argc, char *argv[]) 


{ 


long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 0; 

char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 

long chaining_vector_length = 128; 
long hash_length = 20; 

long text_length; 

unsigned char chaining_vector[128]; 
unsigned char hash[20] ; 

long signature_length = 256; 

long signature_bit_length; 


| ee ee ee ee ee ee ee ee eee 
/* Declares for working with a PKA token 

[ Reeceesessee ss peeseeeeeesesetaeee SS aes see seesescesoeeeeecesceese 
long pub_sec_len; /* Public section length 

long cert_sec_len; /* Certificate section length 

long offset; /* Offset into token 

long tempOffset; /* (Another) Offset into token 

long tempLength; /* Length variable 

char name[64]; /* Private key name 

char SAname[64]; /* Share administration or certifying 


/* key name. 


iSeries: Cryptographic hardware 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


char SAnameASCII[64] ; /* Share admin key name in ASCII 
long SAname_length = 64; /* Length of Share admin key name 
long count; /* Number of bytes read from file 


decimal(5,0) xlate_length = 64; /* Packed decimal variable 


/* needed for call to QDCXLATE. 
FILE «fp; /* File pointer 
if (argc < 3) /* Check the number of parameters passed 


printf("Need to enter a public key name and SA key\n"); 
return 1; 


} 


name[0] = 0; /* Make copy of name parameters 
strcpy(name,argv[1]); 
memset (SAname, ' ', 64);  /* Make copy of Share Admin key name 


memcpy (SAname, argv[2],strlen(argv[2])); 


fp = fopen(name,"rb"); /* Open the file containing the token 
if (!fp) 

{ 

printf("File %s not found.\n",argv[1]); 

return 1; 

} 
memset (token,0,2500) ; /* Read the token from the file 


( 
count = fread(token,1,2500, fp); 
fclose(fp); 


/* Determine length of token from length 


/* bytes at offset 2 and 3. 
token_len = ((256 * token[2]) + token[3]); 
if (count < token_len) /* Check if whole token was read in 


printf("Incomplete token in file\n"); 
return 1; 


} 


[RRR KER AK KR AKER A KKK KKK KKK KK KKK KKK IKKE KKK EK KIER AKER AKER KK | 


/* Find the certificate offset in the token x/ 
/* x/ 
/* The layout of the token is */ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x/ 
/* x/ 


[RRR KER AKER A KKK A KKK AK KEK KKK KKK KK KKK KKK KK EK KIER AKER AKER KK | 


pub_sec_len = ((256 * token[10]) + token[11]); 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 


offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate section 


/* length from the length bytes at 


/* offset 2 of the section. 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 
tempOffset = offset + 4; /* Set offset to first subsection 


/* Parse each subsection of the certificate until the */ 
/* signature subsection is found or the end is reached.*/ 
/* (Identifier for signature subsection is Hex 45.) */ 


while(token[tempOffset] != 0x45 && 
tempOffset < offset + cert_sec_len) 
{ 


tempOffset += 256 * token[tempOffset + 2] + token[tempOffset+3] ; 
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/* Check if no signature was found before the end of */ 


/* the certificate section. */ 
/xsecteensssesseseseceseeeessessoseeseessessecesoseese */ 
if (token[tempOffset] != 0x45) 

{ 

printf("Invalid certificate\n"); 

return 1; 

} 


[BRK RKER KKK AKEKR AKER A KKK KK EIR KER AK KEK KEKE KKK AKER EKER EK | 
/* Replace Private key name in certificate with the */ 
/* Share admin key name (expressed in ASCII). x*/ 
[BRK RK ERK K RRA KE RIKKI KKK KK EIR KER IKKE AKER A AKER EKER | 
text_length = tempOffset - offset + 70; 

memcpy (SAnameASCII,SAname, 64) ; 


[Rasseresssscacsecsessassessessesesssess seocseessscfese «/ 
/* Convert the Share Admin key name to ASCII */ 
[Reess6 Fe see see sesseee se seae es ee eee ee se see See ee sees «/ 
QDCXLATE(xlate_length, SAnameASCII, "QASCII "S "Qsys mn) 


memcpy (&token[tempOffset + 6], SAnameASCII, 64); 


[KERR KKK KKK AKER A KKK KKK KKK IK KKK A KKK A KKK KAKA KKK AKER AREER | 
/* Hash the certificate */ 
[EKER KKK AK ERIK KKK KEK AKER KER AK KEIRA KKK EKA KERA KERR | 
memcpy((void*)rule_array,"SHA-1 ",8); 

rule_array_count = 1; 

chaining_vector_length = 128; 

hash_length = 20; 


CSNBOWH( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&text_length, 
&token[offset], 
&chaining_vector_length, 
chaining_vector, 
&hash_length, 
hash) ; 


if (return_code != 0) 


printf("One_Way_Hash Failed : return reason %d/%d\n", 
return_code, reason_code); 
return 1; 


} 


[BERR KKK AKER AKER IKK A KKK KK EIR KER AKKEA KEI KK AKER IKE ERK KK | 
/* Create a signature x/ 
[RRR KKK A KKK KKK KKK KKK KKK IK KKK KK KAKA KKK KKK AKER AK KERK KE | 
memcpy ((void*)rule_array,"ISO-9796",8) ; 

rule_array_count = 1; 


CSNDDSG( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&SAname_length, 

SAname, 

&hash_length, 

hash, 
&signature_length, 
&signature_bit_length, 
&token[tempOffset+70]); 
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if (return_code != Q) 


printf("Digital Signature Generate Failed : return reason %d/%d\n", 
return_code, reason_code); 


return 1; 

} 
[xeesa sass eHsesseesescesseesesseessssesssse-sseee */ 
/* Check if the new signature is longer than the */ 
/* original signature x/ 
[#eeeceeeceeeesqsecsl Sena l ses sees essaesaeeeee ee */ 


if((token[tempOffset + 2] * 256 + token[tempOffset + 3]) - 70 != 
signature_length) 


printf("Signature Length change from %d to %d.\n", 
token[tempOffset + 2] * 256 + token[tempOffset + 3] - 70, 
signature_length) ; 


/* Adjust length in signature subsection */ 
token[tempOffset + 2] = signature_length >> 8; 
token[tempOffset + 3] = signature_length; 


/* Adjust length in certificate section */ 
token[offset + 2] = (text_length + signature _length) >> 8; 
token[offset + 3] = text_length + signature_length; 


/* Adjust length in token header section */ 

tempLength = 8 + pub_sec_len + 68 + text_length + 
signature_length; 

token[2] = tempLength >> 8; 

token[3] = tempLength; 

} 

else tempLength = token[2] * 256 + token[3]; 


[RR KK KKK KK ERA KK ER KEKE AK KERR KEKE RAKE EKER | 


/* Write certified public key out to a file */ 


[RRR KR KERR KER AK KEK KKK KKK AK KKK KEK AKER AKER KK | 


strcat(name,".CRT"); /* Append .CRP to filename */ 
fp = fopen(name,"wb"); /* Open the certificate file */ 
if (!fp) 
{ 
printf("File open failed for output\n"); 
} 
else 


fwrite(token, 1, tempLength, fp); 
fclose(fp); 
printf("Public token written to file %s.\n",name) ; 


} 
} 


Example: ILE RPG program for certifying a public key token 


Change this program example to suit your needs for certifying a public key token. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


DA KRAKK KKK KKK ERK KEKE KKK KERR KERR KERR RRR ER RRR KEK RRR RRR RRR ER ERR RRR 
D* CERTKEY 

Dx« 

D* Sample program to certify a CCA public key certificate to be 
D* used for master key cloning. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 
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Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 

D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
D* IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

Dx Parameters: FILENAME - File containing public key token 
Dx RETAINED_KEY_NAME - Name of key to certify token 
Dx« 

D* Example: 

D* CALL PGM(CERTKEY) PARM(MYKEY.PUB CERTKEY) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CERTKEY) SRCFILE(SAMPLE) 
D* CRTPGM PGM(CERTKEY) MODULE(CERTKEY) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

Dx Note: Authority to the CSNDDSG and CSNBOWH service programs 
D« in the QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Digital Signature Generate (CSNDDSG) and One Way Hash (CSNBOWH) . 


Dx« 

DARK RK KKK KKK KER KK KKK KKK KKK KEKE KKK KR RK KKK KEK KERR KEK RRR KEK RRR RRR 
DPeeSesSe ee aee Se rece ease eee esa ee See eestor eet ese 
D* Declare variables used by CCA SAPI calls 

Peco sec ese alee eee elec ele see SSeS eee cease cece S eco sees 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXTTDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT Ss 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Token length 

DTOKENLEN S 9B 0 INZ(2500) 

D* ** Token and array for subscripting token 
DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

D* ** Chaining vector length 

DCHAINVCTLEN S 9B @ INZ(128) 

D* ** Chaining vector 

DCHAINVCT S 128 

D* ** Hash length 

DHASHLEN S 9B © INZ(20) 

Dx ** Hash 

DHASH S 20 

D* ** Text length 

DTXTLENGTH S 9B 0 

D* ** Signature length 

DSIGLENGTH S 9B 0 INZ(256) 

D« ** Signature length in bits 
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DSIGBITLEN S 


Peet ese aeeaen Soe scee ss 
D* Declare variables 
Deer esc ae sees seseeteH 
Dx« ** 
Dx ** 
DNAMEPTR S 
DNAME Ss 
Dx ** 
DSANAMELEN S 
Dx ** 
DSANAME Ss 
Dx« ** 
DSANAMEASC S 
Dx ** 
DCRTSECLEN Ss 
Dx ** 
DPUBSECLEN S 
Dx ** 
DTKNINDEX S 
Dx« ** 
DTMPINDEX Ss 
Dx« ** 
Dx ** 
DLENSTRUCT DS 
DMSB 

DLSB 

DLENGTH 

Dx **k 
DFILED 5 
Dx« ** 
DPATH Ss 
DPATHLEN S 
Dx« ** 
Dx« ** 
DOFLAGW Ss 
Dx ** 
DOFLAGR S 
Dx« ** 
DXTABLE S 
DLIB Ss 
DXLATLEN S 
D 

Dx« 


NAMEPTR and NAME are used for copying 
private key name 
* 
64 BASED (NAMEPTR) 
Share administrator (certifying key) name length 
9B 0 
Share administrator (certifying key) name 
64 
Share administrator name expressed in ASCII 
64 
Certificate section length 
9B 0 
Public key section length 
9B 0 
Index into PKA key token 
9B 0 
Index into PKA key token 
9B 0 
Structure used for aligning 2 bytes into a 
2 byte integer. 
2 
1 1 
2 2 
1 2B 0 
File descriptor 
9B 0 
File path and path length 
80 INZ(*ALLX'00') 
9B 0 
Open flag - Create on open, open for writing, 
and clear if exists 
101 0 INZ(X'4A') 
Open Flag - Open for Read only 
101 @ INZ(1) 


Declares for calling QDCXLATE API 
10 INZ('QASCII ') 
10 INZ('QSYS ') 
5 © INZ(64) 


DAKAR KKKKKKK KER KKK KKK KR ERK KERR KERR KERR RRR RRR REE KERR EERE RERERE 


D* Prototype for Digital Signature Generate (CSNDDSG) 


DARK RKKKKK KK KEK KKK KEK KKK ERK KKK KKK KEKE KEK KKK KEK KEKE RRR RRR RRR ERE 


DCSNDDSG PR 
DRETCOD 
DRSNCOD 
DEXTDTALN 
DEXTDT 
DRARRYCT 
DRARRY 
DKEYIDLEN 
DKEYID 
DHSHL 
DHSH 
DSIGFLDL 
DSIGBTL 
DSIGFLD 
Dx« 


) 
9B 0 
) 


OPTIONS (*VARSIZE) 


20 OPTIONS (*VARSIZE) 


oe 


9B 


256 OPTIONS (*VARSIZE) 


DA KRRKKKKK KKK ERK KKK KKK KERR KEK KEK K RRR RRR ER KER RRR RRR RRR KER ERERE 


D* Prototype for One_| 


Way_Hash (CSNBOWH) 


DA KRKKKKKKKK KER KEK KERR KEKE RK KERR KEK KERR RRR RRR RE ER KERR RRR ER ERRERE 


DCSNBOWH PR 
DRETCOD 


9B 0 
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DRSNCOD 9B 0 

DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DTXTLEN 9B 0 

DTXT 500 OPTIONS (*VARSIZE) 
DCHNVCTLEN 9B 0 

DCHNVCT 128 

DHSHLEN 9B 0 

DHSH 20 

Dx« 

Dx« 

DARK AKKKKKK KK ER KKK KEK KKK KKK KKK KEK KKK RRR KERR KKK KERR KR ERK KR RRR 
D* Prototype for open() 


DA KRKKKKKKK KK ER KKK EK KK KERR KERR KKK REE RK RRR RRR ERR KER ER KEK RERREREE 
D« value returned = file descriptor (OK), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

D* Open flags 

D 9B 0 VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U 0 VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 

DARA RKKKKKKK KKK KKK KEK KKK ERK KEKE RK KEKE KKK KER KR RRR KKK ERK RRR KERR KERR RR RRKEK KR 
D* Prototype for read() 

DARK K KKK KKK KK ER KKK KEK KKK ERK KKK KEK K KERR RK KKK KEK KR ERR RR RR KK REREKK 


Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be read 

D 9B 0 VALUE 

Dx« 


DARK KAKA KKK KK ERE KK KEK KK KERR KERR KR RRR KK ERK RRR RRR RE RK RR EKER RE RR ERRERREER 


D* Prototype for write() 


DAR RAKKKKK KK KER KEK KEK KKK KR KKK KR KKK KERR KK RKE KKK KERR KR RKE KK REE 
D« value returned = number of bytes written, or -1 


Dwrite PR 9B 0 EXTPROC('write') 

D« File descriptor returned from open() 

D 9B 0 VALUE 

D* Output buffer 

D 2500 OPTIONS (*VARSIZE) 

D* Length of data to be written 

D 9B 0 VALUE 

Dx« 

DARK RK KARR KKK KKK KEKE KKK KER KKK RRR KK KE KKK KER KKK RRR KK RRR KR RR KEK KERR RRREKE KERR 
D* Prototype for close() 

DA RRAK KKK KKK KEKE KKK KKK KER KEKE RRR RRR RR KK ER KR RRR RRR EER KER RRR KEE EER REERKEKRERE 
Dx value returned = 0 (OK), or -1 

Dclose PR 9B 0 EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

D¥tecbaee ee ase es eS eee eee eee ces eee sees seem eee eee eee eee sk aeeas 
Dx **x Declares for sending messages to the 

D« ** job log using the QMHSNDPM API 

D¥eeseecesenn see ce cease eee ae el sees esse seme ese ese eS See Stee Sees 
DMSG S 75 DIM(7) CTDATA PERRCD(1) 
DMSGLENGTH S 9B @ INZ(75) 

D DS 

DMSGTEXT 1 75 
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DSAPI 1 7 


DFAILRETC 41 44 

DFAITLRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFTLE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ms) 
DSTACKCOUNTER Ss 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 
III I III I I III II IR I III I Ik 
Cx START OF PROGRAM * 
GCitttt ttt ttt C CCS ee ee ee ee ee ee ee eee 
C *ENTRY PLIST 

C PARM FILEPARM 32 
C PARM CKEY 32 


CR K KK KKK KKK KKK KEK RK KEK KEK ERK KK EKER KE KK EKER ERE RK EKER ERE RR ERR ERE 
Cx Open certificate file 

CR KKK KK KKK KKK KEK KEKE KERR EK ERK KK RK EKER KEK RRR ER ERK RR ERE RRR ERREERE 
Cx Sie eeeee eee ee ese se * 


Cx  »** Build path name * 


Cx Bere s eos eee see eee * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx Se eseeeese nee ssessesse * 

Cx * Open the file * 

Cx Joseesa=so=sasasosoes5= * 

C EVAL FILED = open(PATH: OFLAGR) 
Cx (esederesnenesseseesses * 

Cx »* Check if open worked * 

Cx« KecoceceocososecueSee ce * 

C FILED IFEQ -1 

Cx* SoS Seeee eee eee eee ee eee eS * 

Cx * Open failed, send an error message * 

Cx« Meeseceescees= ceeessessesseeeneseac== * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx« 

C ENDIF 

Cx NI ssssscsscessvst assesses sees ease ssessceessee cesses * 
Cx * Open worked, read certificate and close the file * 
Cx oso ee sees ces ese eee eset ee eee ele eee seece ee * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx* 

Cx Keres csi ees sake see eese esas e See * 

Cx * Check if read operation was OK * 

Cx Keoessssesscssesecoosscecssesscasssaess * 

C TOKENLEN IFEQ -1 

C MOVEL MSG (2) MSGTEXT 

C EXSR SNDMSG 

C ENDIF 

Ce 

Cx Meeeeesass= = SeSa= == ==- S55 5-S———6=— === * 

Cx * Check if certificate length is valid * 

Cx* tocasuaanaacacessen cece asses eecesceee * 

C EVAL MSB = TOKENARRAY (3) 

C EVAL LSB = TOKENARRAY (4) 

C LENGTH IFLT TOKENLEN 

Cx Weeee seal eeseseseeseeteeee eee ee Sees * 

Cx * Certificate length is not valid * 

Cx Meese cee ceessess eos cesses seeseeeeece * 

C MOVEL MSG(3) MSGTEXT 
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C EXSR SNDMSG 


C RETURN 
C ENDIF 
Ce 


CR KKK KKK KEK KKK EKER KEK K EK KKK EKER KKK ER KEK KKK KERR ER ERE RR EK ERE RR EKER EK 
Cx Find the certificate in the token 

C* 

Cx The layout of the token is 

Cx* 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at offset 2 

Cx - Private key name - 68 bytes 

Cx - Certificate section 


C* 

CR KKK KKK KEK KKK KKK KKK KEK KKK ERE KK RK EK KEK KKK KERR EK ERK EKERKE RK EKER 

C* he a ir att an mi a ee * 
Cx * Certificate starts after the public key header section * 
C* ee a a ics a a i a is * 
C EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 

Cx« 

Cx* csc cncsensannannaasceeeasaeteaecoseoass * 

Cx * Determine length of certificate section * 

C* a ay a a a a ac meee * 

C EVAL MSB = TOKENARRAY(TKNINDEX + 2) 

C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 

C EVAL CRTSECLEN = LENGTH 

C EVAL TMPINDEX = TKNINDEX + 4 

C* 

C* Cee ee Se oo * 

Cx * Parse each subsection of the certificate until the * 


Cx * Signature subsection is found or the end is reached.* 


Cx * (Identifier for signature subsection is Hex 45.) * 
C* heel teeee esos eebeeeee eet eect ee ce eee eee eee eee eee ee * 

C DOW (TOKENARRAY (TMPINDEX) <> X'45') AND 
C (TMPINDEX < TKNINDEX + CRTSECLEN) 
C EVAL MSB = TOKENARRAY(TMPINDEX + 2) 

C EVAL LSB = TOKENARRAY(TMPINDEX + 3) 

C TMPINDEX ADD LENGTH TMPINDEX 

C ENDDO 

Cx* 

Cx* Fesssssoe sos sossecssassccescessssccsssecesceseseesescus * 

Cx * Check if no signature was found before the end of * 
Cx * the certificate section. * 
C* Peesssssssss se scesse sec seeseese sce ses coe cose eee ees * 

C IF TOKENARRAY (TMPINDEX) <> X'45' 

C MOVEL MSG (4) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 


CR KKK KK KK EK KKK KEKE KK EKER KERR ER ERK EKER ERR ERE RR ER ERE RR EK ERE RR EKER 


Cx Sign the Certificate 


CR KKK KKK KEK KKK KKK KR KEKE KKK KEKE KKK KER KKK RK RRR EKER KERR EKER ERR EKER EK 


Cx* Licesaania aaa nansansceeeaeeeaSece vases Seeeceocesce= * 
Cx * Convert the Certifying Keyname to ASCII * 
C* se i i a a el ct le a ac cr * 
C EVAL SANAMELEN = %LEN(%TRIM(CKEY) ) 
C SANAMELEN SUBST CKEY:1 SANAME 

C MOVEL SANAME SANAMEASC 

C CALL "QDCXLATE' 

C PARM XLATLEN 

C PARM SANAMEASC 

C PARM XTABLE 

C PARM LIB 
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RAIA DABMAIAAARWAD AIDA aOAlAaA000 00:0 0:0 
+ + + + + + F F HF + + 


Keowee ee * 
* Replace the private key name in the certificate * 
Kee eee ee * 
EVAL NAMEPTR = %ADDR(TOKENARRAY (TMPINDEX + 6)) 
MOVEL SANAMEASC NAME 
Kee eee ee ee a * 
* Calculate length of data to hash * 
* TKNINDEX is the start of the certificate, * 
* TMPINDEX is start of signature subsection, * 
* signature subsection header is 70 bytes long * 
Kee ee ee * 
EVAL TXTLENGTH = TMPINDEX - TKNINDEX + 70 
Kee eee - * 
* Set the keywords in the rule array * 
Kee ee * 
MOVEL "SHA-1 RULEARRAY 
Z-ADD 1 RULEARRAYCNT 
Kee eee - - - - - - * 
* Call One Way Hash SAPI * 
Kee e eee -- e * 
CALLP CSNBOWH (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
TXTLENGTH: 
TOKENARRAY (TKNINDEX) : 
CHAINVCTLEN: 
CHAINVCT: 
HASHLEN: 
HASH) 
Kee ---- * 
* Check the return code * 
Kee eee - -- - -  - -  - - - - * 
RETURNCODE IFGT 0 
Kee ee * 
* Send failure message * 
Kee ----- * 
MOVEL MSG(5) MSGTEXT 
MOVE RETURNCODE FAILRETC 
MOVE REASONCODE FAILRSNC 
MOVEL "CSNBOWH' SAPI 
EXSR SNDMSG 
RETURN 
ENDIF 
Kee e eee -  e * 
* Set the keywords in the rule array * 
Kee eee * 
MOVEL 'TS0-9796' RULEARRAY 
Z-ADD 1 RULEARRAYCNT 
Kee eee - - e - * 
* Adjust TMPINDEX to where signature starts* 
* jn the certificate * 
Kee ee -- - - * 
TMPINDEX ADD 70 TMPINDEX 
Kee eee  - * 
* Set the Key name length * 
Kee ee -- * 
Z-ADD 64 SANAMELEN 
Kee eee ee ee ee * 
* Call Digital Signature Generate SAPI * 
Kee ee - - * 
CALLP CSNDDSG (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 


Chapter 4. 4758 Cryptographic Coprocessor for iSeries 


237 


238 


C RULEARRAYCNT: 

C RULEARRAY : 

C SANAMELEN: 

C SANAME : 

C HASHLEN: 

C HASH: 

C SIGLENGTH: 

C SIGBITLEN: 

C TOKENARRAY (TMPINDEX) ) 
Ce Sess Seo eSses=— Ss os-se == * 

Cx »* Check the return code * 

CX  Wessassesseccasoeeessosce * 

C RETURNCODE IFGT 0 

Cx* Vessossccostesssosesecee * 

Cx * Send failure message * 

C* socieeossescses enue eseces * 

C MOVEL MSG (5) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNDDSG' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

C* 

(a eee eee ee eee eee * 

Cx »* Check if the new signature is longer than the * 

Cx * original signature * 

(Ce Caeseesseseocaaseaseasesoseaseeseeseassaaseossesss * 

Cx *x Adjust TMPINDEX back the start of the subsection 

C TMP INDEX SUB 70 TMP INDEX 

Cx ** Get two byte length of subsection 

C EVAL MSB = TOKENARRAY(TMPINDEX + 2) 
C EVAL LSB = TOKENARRAY(TMPINDEX + 3) 
Cx ** Subtract length of subsection header 

C LENGTH SUB 70 LENGTH 

Cx ** Compare old length with new length 

C LENGTH IFNE SIGLENGTH 

C* (seaeeceeoeesceeseceesoaasSeaceaseens = * 

Cx * Adjust certificate lengths * 

C* Seca eae ecesKsaceea scence ceeseeces * 

Cx ** Adjust signature length 

C EVAL LENGTH = SIGLENGTH 

C EVAL TOKENARRAY (TMPINDEX + 2) = MSB 
C EVAL TOKENARRAY (TMPINDEX + 3) = LSB 
Cx ** Adjust certificate section length 

C EVAL LENGTH = LENGTH + TXTLENGTH 

C EVAL TOKENARRAY (TKNINDEX + 2) = MSB 
C EVAL TOKENARRAY (TKNINDEX + 3) = LSB 
Cx ** Adjust length in token header section 

C EVAL LENGTH = LENGTH + 8 + PUBSECLEN + 68 
C EVAL TOKENARRAY (3) = MSB 

C EVAL TOKENARRAY (4) = LSB 

C Z-ADD LENGTH TOKENLEN 

C ENDIF 

C* 


CR KKK KKK KKK KKK KKK KKK KEK KKK ERE KK RK ER KEK KEKE KR ER ERK RR EK ERE RR EKER 
Cx Write certified public key out to a file 

CR KKK KKK KKK KKK KEKE RR KK ERK KK ERE KK KK ERK KK KKK KR ER ERK RR EK ERE RR EKER E 
Cx ** Build path name 


C EVAL %SUBST (PATH: PATHLEN+1:4) = '.CRT' 
C* 

Cx *x Open the file 

C* 

C EVAL FILED = open(PATH: OFLAGW) 

C* 

Cx xx Check if open worked 

Cx 
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C FILED IFEQ -1 


Cx* 

Cx ** Open failed, send an error message 

Cx« 

C MOVEL MSG (6) MSGTEXT 

¢ EXSR SNDMSG 

Cx* 

C ELSE 

Cx« 

Cx ** Qpen worked, write certificate out to file and close file 
Cx« 

C CALLP write (FILED: 

C TOKEN: 

C TOKENLEN) 

C CALLP close (FILED) 

Cx« 

Cx ** Send completion message 

C* 

C MOVEL MSG(7) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 41: PATHLEN + 4) = 
C %SUBST(PATH: 1: PATHLEN + 4) 
C EXSR SNDMSG 

C ENDIF 

Cx« 

C SETON LR 
Cx« 


CR KKK KK KKK KKK KEKE KR EKER KER ERE KK RK EKER KEK ERR EKER ERR EKER ER ERR ERE 


Cx Subroutine to send a message 
CR R KKK KKK KKK KK KKK KKK KEK KEK ERK KK EKER KERR RK KERR ER EKER KEKE KERR ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


** 

The input file could not be opened. 

There was an error reading from the file. 

The length of the certificate is not valid. 

The certificate is not valid. 

CSNBOWH failed with return/reason codes 9999/9999. 
The output file could not be opened. 

The certified token was written to file 


Example: ILE C program for obtaining a master key share 
Change this program example to suit your needs for obtaining a master key share. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


[eeses ces seenes esse cose seer aes ane sseeaeoe aeons ese eeaas=aeeeeseseeaS */ 
/* GETSHARE x/ 
/* x/ 
/* Sample program to obtain a master key share as part of the x/ 
/* master key cloning process. */ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
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/* tested under all conditions. IBM, therefore, cannot 

/* guarantee or imply reliability, serviceability, or function 
/* of these program. All programs contained herein are 

/* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
/* these programs and files. 

/* 

/* 

/* Note: Input format is more fully described in Chapter 2 of 
/* IBM 4758 CCA Basic Services Reference and Guide 

/* (SC31-8609) publication. 

/* 

/* Parameters: Share number 

/* Name of share sender private key 

/* Name of certifying key 

/* Stream file containing receiver certificate 

/* 

/* 

/* Example: 

/* CALL PGM(GETSHARE) PARM(2 SENDR SAKEY RECVR.PUB) 

/* 

/* 

/* Note: This program assumes the card with the profile is 

/* already identified either by defaulting to the CRPO1 
/* device or by being explicitly named using the 

/* Cryptographic_Resource Allocate verb. Also this 

/* device must be varied on and you must be authorized 
/* to use this device description. 

/* 


/* The Common Cryptographic Architecture (CCA) verbs used is 
/* Master_Key_ Distribution (CSUAMKD). 

/* 

/* Use these commands to compile this program on iSeries: 

/* ADDLIBLE LIB(QCCA) 


/* CRTCMOD MODULE(GETSHARE) SRCFILE(SAMPLE) 

/* CRTPGM PGM(GETSHARE) MODULE (GETSHARE) 

/* BNDDIR(QCCA/QC6BNDDIR) 

/* 

/* Note: Authority to the CSUAMKD service program 

/* in the QCCA library is assumed. 

/* 

JeosossesssoessasseecsesssoscssssecseleccesSoceee Sessesesocessesossce 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 
#include "decimal.h" 


extern void QDCXLATE(decimal (5,0), char *, char*, char *); 
#pragma linkage (QDCXLATE, OS, nowiden) 


int main(int argc, char *argv[]) 


[k@eeaaneaa cease sees ees Sess = 5 sea eae ae ae ee eee aaa =e asses 
long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 0; 

char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 

long cloneInfoKeyLength = 500; 
unsigned char cloneInfoKkey[500] ; 
long cloneInfoLength = 400; 
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unsigned char cloneInfo[400]; 
long shareldx; 

char name[64] ; 

char SAname[64] ; 


| Races Seeeemseees sascemaeeeease see sesseecesec ae ==o- ee aes So aeece 
/* Declares for working with a PKA token 
[eseeeSaesentrensSeeetescas eassse ss sessnaeeaeeesceesaeneeetseenuseae 
long pub_sec_len; /* Public section length 

long prv_sec_len; /* Private section length 

long cert_sec_len; /* Certificate section length 

long info_subsec_len; /* Information subsection length 

long offset; /* Offset into token 

long tempOffset; /* (Another) Offset into token 

long tempLength; /* Length variable 

long tempLenl, tempLen2; /* temporary length variables 

char cloneShare[] = "cloneShareQQ"; /* Base cloning share filename 
long count; /* Number of bytes read in from file 


decimal(15,5) shareParm; /* Packed 15 5 var used for converting 
/* from packed 15 5 to binary. Numeric 


/* parms on iSeries are passed as dec 15 
FILE «fp; /* File pointer 
if (argc < 5) /* Check the number of parameters passed 


printf("Need to Share index, Sender name, SA name, and cert\n"); 
return 1; 


} 


/* Convert the packed decimal 15 5 parm 
/* to binary. 
memcpy (&shareParm, argv[1],sizeof(shareParm) ) ; 
shareIdx = shareParm; 
memset(name,' ',64); /* Copy the Private key name parm to a 
memcpy (name,argv[2],strlen(argv[2])); /* 64 byte space padded var. 
memset (SAname,' ',64); /* Copy the Share Admin name parm to a 
memcpy (SAname, argv[3],strlen(argv[3]));/* 64 byte space padded var. 


fp = fopen(argv[4],"rb"); /* Open the file containing the token 
if (!fp) 
{ 


printf("File %s not found.\n",argv[4]); 
return 1; 


} 


memset (token,0,2500) ; /* Read the token from the file 
count = fread(token,1,2500, fp); 


fclose(fp); /* Close the file 
/* Determine length of token from length 
/* bytes at offset 2 and 3. 

token_len = ((256 * token[2]) + token[3]); 

if (count < token_len) /* Check if whole token was read in 


printf("Incomplete token in file\n"); 


return 1; 

} 
[BRK R KER AKER AKER IKK AK KEK KEIR KERRI KK AKKEK KKK AKER AKER KK | 
/* Find the certificate offset in the token */ 
/* */ 
/* The layout of the token is */ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
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/* - Certificate section */ 
/* */ 


[BRK RKER KKK AK KEI KKK KKK KK ERK KER AK KEA KKK KKEK EKER AKER AKER | 


pub_sec_len = ((256 * token[10]) + token[11]); 


offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate secti 


/* length from the length bytes at 


/* offset 2 of the section. 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]) 


[KERR KERIKERI KEI KKK AKK EK KKK IK KER AK KEI KK AKK EA KIER KER KKK EAKEK 
/* Obtain a share 

[RRR KKK AK KR AK KAKA KK IK KK AK KIRKE AK KEK KIRA K ERA KERR EK 
memcpy((void*)rule_array,"OBTAIN ",8); /* Set rule array 
rule_array_count = 1; 


CSUAMKD( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&shareldx, 
name, 

SAname, 
&cert_sec_len, 
&token[offset], 
&cloneInfoKeyLength, 
cloneInfoKkey, 
&cloneInfoLength, 
cloneInfo) ; 


if (return_code != 0) 


printf("Master Key Distribution Failed : return reason %d/%d\n", 


return_code, reason_code); 
return 1; 


} 


else 


{ 


[RRR AKER KK RIK KEK KK EA EKER KKK IKE KK KEKE AKER KK EA KEE A KER 
/* Write signed token out to a file 
[RRR KKK I KK KKK KKK KK EAR KIRKE KK KKK KKK KKK KKK K KAKA KKK KK 


printf("Master Key Distribution worked\n"); 


/* Build file path name 
if (shareIdx < 9) cloneShare[11] = '0' + shareldx; 
else 


{ 


cloneShare[10] = '1'; 
cloneShare[11] = '0' + shareIdx - 10; 
} 
fp = fopen(cloneShare,"wb"); /* Open the file 
if (!fp) 
{ 
printf("File %s not be opened for output.\n",cloneShare) ; 
return 1; 
} 


/* Write out the length of KEK 
fwrite((char*) &cloneInfoKeyLength,1,4, fp); 

/* Write out the KEK 
fwrite((char*)cloneInfoKey,1,cloneInfoKeyLength, fp) ; 

/* Write out the length of inf 
fwrite((char*)&cloneInfoLength,1,4, fp); 
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on 


*/ 


*/ 
*/ 


*x/ 
*/ 
*x/ 


fe) 


*/ 
*/ 
*/ 


*/ 


/* Write out the clone info */ 
fwrite((char*)cloneInfo,1,cloneInfoLength, fp) ; 
printf("CLone share %d written to %s.\n",sharelIdx,cloneShare) ; 


fclose(fp); /* Close the file */ 
return 0; 


} 
} 


Example: ILE RPG program for obtaining a master key share 
Change this program example to suit your needs for obtaining a master key share. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


DA KRAKKKKKKK KER KKK KEK KK KERR KERR KKK KERR KER KER KERR ERR RRR ERK ER ERER ERR 
D* GETSHARE 

Dx« 

D* Sample program to obtain a master key share as part of the 
D* master key cloning process. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
D* IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx 

Dx Parameters: Share number 

D* Name of share sender private key 

Dx Name of certifying key 

Dx Path name of stream file containing receiver certificate 
Dx« 

D* Example: 

D* CALL PGM(GETSHARE) PARM(2 SENDR SAKEY RECVR.PUB) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(GETSHARE) SRCFILE(SAMPLE) 
D* CRTPGM PGM(GETSHARE) MODULE (GETSHARE) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUAMKD service program 
Dx in the QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used is 
D* Master_Key Distribution (CSUAMKD). 
Dx« 


DAKAR KK KKK KK KER KKK ERK KR ERK KEK RRR KR RRR RRR KERR KER KER KR R RRR EERE ERERER 


DxeeSseestssassSsoessessSssaaSsa asses aaa saaaeaa see = Sse === S5 
Dx *x Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE Ss 9B 0 
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Dx« 
DEXITDATALEN 
Dx« 
DEXITDATA 
Dx« 
DRULEARRAYCNT 
Dx« 
DRULEARRAY 
Dx« 
DTOKENLEN 
Dx« 

DTOKEN 
DTOKENARRAY 
Dx« 
DPRVNAME 
Dx« 
DCERTKEY 
Dx« 
DLSTRUCT 
Dx« 

Dx« 
DCLONEKEKL 
DCLONEKEKLC 
Dx« 

Dx« 
DCLONEINFOLEN 
DCLONEINFOLENC 
Dx« 
DCLONEKEK 
Dx« 
DCLONEINFO 
Dx« 
DSHAREIDX 
Dx« 

Dx« 
DLENSTRUCT 
DMSB 

DLSB 
DLENGTH 

Dx« 
DCRTSECLEN 
Dx« 
DPUBSECLEN 
Dx« 
DTKNINDEX 
Dx« 

DOUTLEN 

Dx« 

DFILED 

Dx« 
DPSTRUCT 
DPATH 
DSIDX 
DPATHLEN 
Dx« 

DOFLAGR 

Dx« 

Dx« 

DOFLAGW 

Dx« 
DSHAREFILE 
Dx« 


S 


Exit data length 
9B 0 
Exit data 
4 
Rule array count 
9B 0 
Rule array 
16 
Token length 
9B 0 INZ(2500) 
Token and array for subscripting 
2500 
1 DIM(2500) 
Private key name 
64 
Certifying key name 
64 


Clone KEK length - one is binary form and the 
other is used for reading the value from a file 
9B 0 INZ(500) 
1 4 
Clone info length - one is binary form and the 
other is used for reading the value from a file 
9B 0 INZ(400) 
5 8 
Cloning key-encrypting-key 
500 
Cloning info 
400 
Share index 
9B 0 
Data structure for aligning 2 bytes into 
a 2 bytes integer 


2 
1 1 
2 2 
1 2B 0 
Certificate section length 
9B 0 
Public key section length 
9B 0 
Index into Token array 
9B 0 
Number of bytes to write out to a file 
9B 0 
File descriptor 
9B 0 


File path and length 


80 INZ(*ALLX'00') 
17 12B 0 
9B 0 
Open Flag - Open for Read only 
101 @ INZ(1) 
Open flag - Create on open, open for writing, 
and clear if exists 
101 0 INZ(X'4A') 
Base name of file to store cloning share 
12 INZ('cloneShare00') 


DA RRA KKK KKK KK ERK KKK KKK KERR KERR KK KERR RK RR KEK RRR RRR ER KEK RERRERERK 


D* Prototype for Master_Key Distribution (CSUAMKD) 


DAKAR KKK KKK KK ER KKK ERK KK ERK KERR KKK REE RK RR KER RR ERE RRR KEK ERERER 


DCSUAMKD 
DRETCOD 
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PR 


9B 0 


DRSNCOD 9B 0 


DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DSHRINDX 9B 0 

DKYNAM 64 

DCRTKYNAM 64 

DCRTL 9B 0 

DCRT 2500 OPTIONS (*VARSIZE) 
DCLNKEKL 9B 0 

DCLNKEK 1200 OPTIONS (*VARSIZE) 
DCLNL 9B 0 

DCLN 400 OPTIONS (*VARSIZE) 
Dx« 


DA RRRKK KKK KK ERK KK ERK KK ERK KREKR KERR KERR RRR RRR RE RR RRR ERK RR ERRERER 
D* Prototype for open() 

DA KRK KKK KKK KK ERK KEKE KKK KERR KERR RRR KERR RRR RRR RRR RRR ERK KER ERREER 
Dx value returned = file descriptor (0K), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B 0 VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 


DARK RKKKKK KK KEK KKK KEK KKK KKK KKK KKK KERR RK KER K RRR KER KK RR KEKE RRR KERR RRER ERE 


D* Prototype for write() 


DA KRKKKKKKKK KER KKK KKK KK ERK KERR KKK RRR RRR RRR RK ER ERR ERK ER ERE 
D« value returned = number of bytes written, or -1l 


Dwrite PR 9B 0 EXTPROC('write') 
D« File descriptor returned from open() 

D 9B @ VALUE 

D* Output buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be written 

D 9B @ VALUE 

Dx 


DA KRK KK KKK KK KEK KKK KEK KKK KKK KKK KKK KKK KK KERR RRR KER KK ERK RRR ER ERR REE KER ER 
Dx Prototype for read() 

DARK AKKKKK KKK ERK KK KEK KKK ERK KKK KEK KKK RRR KERR KK RRR RK KR ERK KR ERE 

Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be read 

D 9B 0 VALUE 

Dx 


DA KRKKKKKKKK KEK KKK KERR KEKE KEKE KKK KEKE RE KR RR KR RRR RK REE KERR RRR RER RR RERKER RRR 


D* Prototype for close() 


DARK KKK KKK KK KEK KKK KEK K KK RRR KKK KKK KR KKK KERR RRR KER KR RRR RR E KKK KER KEKE ERE 
D« value returned = @ (OK), or -1 


Dclose PR 9B @ EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx 
PeeSeseecssssecseceseesocccsSesce esse scsscssoseessSeeosesssees 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

Dee a nn ee ee a 
DMSG S) 75 DIM(6) CTDATA PERRCD(1) 
DMSGLENGTH Ss 9B 0 INZ(80) 
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D DS 


DMSGTEXT 1 80 

DSAPI 1 7 

DFAILRETC 4l 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(! ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ") 
DSTACKCOUNTER 5 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 

CRRA KK KKK KKK KKK KER KKK KERR KEK KEKE RRR EKER ERR RE RE RE RE RAEERERERERERERE 
Cx START OF PROGRAM * 
C* * 
C *ENTRY PLIST 

C PARM SINDEX 15.5 
¢ PARM PRVKEY 32 
C PARM SAKEY 32 
C PARM FILEPARM 32 


CR KKK KKK KEK KKK KKK RRR EK KKK ERE KK RK EKER KEKE RR EKER KERR EKER ERK EKER EK 


Cx Open certificate file 
CR KKK KKK KEK KKK KEKE KK KK EKER KEKE RK EKER KERR EK ERR ER ERE RR EKER RR EKER 


Cx HersesaceesossassHest= * 

Cx  »** Build path name * 

Cx* Koisecscoesetecoonsosees * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx PHersconcossnssadenese] * 

Cx * Open the file * 

Cx teeeececon see seseeeces * 

C EVAL FILED = open(PATH: OFLAGR) 
Cx Fessesseeseeeeeeseeeses * 

Cx  »* Check if open worked * 

Cx* $eeeSosceessescoenscecs * 

C FILED IFEQ -1 

C* (eases eSeeeetiaeeebee ances coco ecceccse * 

Cx * Open failed, send an error message * 

C* ogewacesaaeenaskaccacesoaSesoSssceSsce * 

C MOVEL MSG (1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C* 

C ENDIF 

Cx* tecceceSseesse eee eee assaes ese one oeeseseeesesce * 
Cx * Open worked, read certificate and close file * 
Ce Wess Selo etesesee see ssceess ssa eee eee ete secee see * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx* 

Ce Feces seers o atest eseeee ese ese secee eee * 

Cx * Check if read operation was OK * 

Cx NeSSs cee ses ss esloaae=eseeaeeaaseS-seseae * 

Cc TOKENLEN IFEQ -1 

C MOVEL MSG (2) MSGTEXT 

C EXSR SNDMSG 

C ENDIF 

Cx 

Cx* See ee ee ee oe et * 

Cx * Check if certificate length is valid * 

Cx * The length bytes start at position 3 * 

Cx eee eee ee ee * 

C EVAL MSB = TOKENARRAY (3) 

C EVAL LSB = TOKENARRAY (4) 
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C LENGTH TRLT. TOKENLEN 


Cx* sso e nen S al R esa eS * 

Cx * Certificate length is not valid * 

Cx ee ee eee ee * 

C MOVEL MSG(3) MSGTEXT 
C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 


CXR KK KKK KKK KKK KERR KK ERK EK ERK KKK KEKE KR EK KERR EKER KER ERE RRR ERR ERE 
Cx Find the certificate in the token 

Cx* 

Cx The layout of the token is 

Cx« 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at position 3 (11 overall) 
Cx - Private key name - 68 bytes 

Cx - Certificate section 

Cx« 

Cx Note: 1 is added because RPG arrays start at 1. 

CR KKK KK KKK KKK KEKE KR KK ERK ER ERK KK EKER KERR EKER ER ERR RR ERE REE ERREERE 


C EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
Cx* 

Cx* icc aanan a nana Cesee ae aaa tae em ae * 

Cx * Determine length of certificate section * 

Cx * Length bytes are at position 2 of the * 

Cx * section. 

Cx* Se ih Si a a a a ti a * 

C EVAL MSB = TOKENARRAY(TKNINDEX + 2) 
C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 
C EVAL CRTSECLEN = LENGTH 

Cx* 


CR K KK KK KK KKK KKK KEK RE KR ERK ER ERE KK RK EKER KEK ERR ER ERR RR ERE RRR ERR ERE 


Cx Obtain a certificate 
CR KKK KK KEK KKK KK KKK KR KKK KK EK ERK KK EK ERR KK EKER EKER KERR ER ERK ERRERE 


Cx wos sscssessouscee sesso essescoeSeasssscssece * 

Cx  »* Set share index number * 

C* »* (Convert from packed 15 5 to binary) * 

Ce AkeSeseeSsesscssoseose soe sseoe ese wossscocese * 

C Z-ADD SINDEX SHAREIDX 

Cx essa ose sosescsceeSsessesscecoseasssscoscs= * 

Cx »* Set private key name * 

Cx (ieee ese seee este Ssse eee eee See ee ee * 

C EVAL LENGTH = %LEN(%TRIM(PRVKEY) ) 
C LENGTH SUBST PRVKEY:1 PRVNAME 

Cx Fee Se csessesecsc ees see se eee eee eee eee eee * 

Cx  »* Set certifying key name * 

Cx Pemba sete esseeseehect ese seecee eee ee see ete * 

C EVAL LENGTH = %LEN(%TRIM(SAKEY) ) 
C LENGTH SUBST SAKEY : 1 CERTKEY 

Cx Fee Secs scee ec Se see see see lee eee see eeeee * 

Cx »* Set the keywords in the rule array * 

Cx ee eee eee ee * 

C MOVEL ‘OBTAIN ' RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 
Cx Peeoeecseesesesee See see se ee eee tees * 

Cx »* Call Master Key Distribution SAPI * 

Cx Yesoes=seeseccoessasesassao Ses eeo ease * 

C CALLP CSUAMKD (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 
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C SHAREIDX: 
C PRVNAME: 

C CERTKEY: 

C CRTSECLEN: 
C TOKENARRAY (TKNINDEX) : 
C CLONEKEKL: 
C CLONEKEK: 
C CLONEINFOLEN: 
C CLONEINFO) 
Ce Sess S2oeSses—-— Ss os-se == * 

Cx * Check the return code * 

CX  Wessassesseccasoeeessosce * 

C RETURNCODE IFGT 0 

Cx* Pesscscscssesossessceccceu * 

Cx * Send failure message * 

C* Peeieeseeseeaseessee aces * 

C MOVEL MSG(4) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

Cc MOVE REASONCODE FAILRSNC 

C MOVEL "CSUAMKD' SAPI 

¢ EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 


CR KKK KKK KEK KKK KEKE KR KK EK KKK ERE KK RK ER KEK KKK KERR ER ERK RR EKER ERK EKER 


Cx Write share out to a file 
CR KKK KKK EK KKK KKK KKK KERR ER EKER KKK EK KERR EKER KER ERR RR EK ERE RR EKER 


Cx «x Build path name 


C MOVEL *ALLX'00' PATH 

C MOVEL SHAREFILE PATH 

¢ SIDX ADD SHAREIDX SIDX 

C SHAREIDX IFGE 10 

C SIDX ADD 246 SIDX 

C ENDIF 

C* 

Cx «x Open the file 

(7 

C EVAL FILED = open(PATH: OFLAGW) 
Cx* 

Cx «x Check if open worked 

C* 

C FILED IFEQ -1 

Cx* 

Cx ** Open failed, send an error message 

C* 

C MOVEL MSG(5) MSGTEXT 

C EXSR SNDMSG 

C* 

C ELSE 

C* 

Cx ** Open worked, write certificate out to file and close file 
C* 

C Z-ADD 4 OUTLEN 

C CALLP write (FILED: 

C CLONEKEKLC: 
C OUTLEN) 

C CALLP write (FILED: 

C CLONEKEK: 

C CLONEKEKL) 
C CALLP write (FILED: 

C CLONEINFOLENC: 
C OUTLEN) 

C CALLP write (FILED: 

C CLONEINFO: 
C CLONEINFOLEN) 
C CALLP close (FILED) 

Cx* 
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Cx ** Send completion message 


Cx* 

C MOVEL MSG (6) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 32: 12) = 
C %SUBST(PATH: 1: 12) 
C EXSR SNDMSG 

C ENDIF 

Cx* 

C SETON 

Cx« 


CR K KK KKK KKK KK KKK KKK KE KK EK ERK KK EKER KEK RRR KERR ER ERK EKERKERKERRERE 


Cx Subroutine to send a message 


CR K KK KK KKK KKK KEKE KKK KER KER ERE KK RK ERE RK EK ERR ER ERE RR EKER RR ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


The input file could not be opened. 

There was an error reading from the file. 

The length of the certificate is not valid. 
CSUAMKD failed with return/reason codes 9999/9999. 
The output file could not be opened. 

The share was written to file 


Example: ILE C program for installing a master key share 


LR 


Change this program example to suit your needs for installing a master key share. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


important legal information. 


PUTSHARE 


Sample program to install a master key share as part of the 
master key cloning process. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these program. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: Share number 
Name of share receiver private key 
Name of certifying key 
Stream file containing sender certificate 
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/* */ 


/* x/ 
/* Example: */ 
/* CALL PGM(PUTSHARE) PARM(2 RECVR SAKEY SNDR. PUB) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verbs used is x*/ 
/* Master_Key Distribution (CSUAMKD). */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(PUTSHARE) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(PUTSHARE) |= MODULE(PUTSHARE) */ 
/* BNDDIR(QCCA/QC6BNDDIR) */ 
/* x/ 
/* Note: Authority to the CSUAMKD service program */ 
/* in the QCCA library is assumed. */ 
/* x/ 
[#esrenSceis ohaSs sees esas ase le dee ce sae e ease seat eese So eee bese oe «/ 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 
#include "decimal.h" 


extern void QDCXLATE(decimal (5,0), char *, char*, char *); 
#pragma linkage (QDCXLATE, OS, nowiden) 


int main(int argc, char *argv[]) 


| ee ee ea et «/ 
/* Declares for CCA parameters x/ 
J esaceseusasossessaseeseesessast sees sos ss ssa ccs ss essa sheesessesescas */ 


long return_code = 0; 

long reason_code = Q; 

long exit_data_length = 0; 
char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 

long cloneInfoKeyLength = 500; 
unsigned char cloneInfokey[500] ; 
long cloneInfoLength = 400; 
unsigned char cloneInfo[400]; 
long shareldx; 

char name[64]; 

char SAname[64] ; 


[kee ee eteeesaea se Seco sees aae ean asses aSeeet eee nesses eee sesesee seas */ 
/* Declares for working with a PKA token */ 
/#secescenesesosacsseeseeeessesseseereessues seesuesoseeSsoesenS esses «/ 
long pub_sec_len; /* Public section length x/ 
long prv_sec_len; /* Private section length x/ 
long cert_sec_len; /* Certificate section length */ 
long info_subsec_len; /* Information subsection length x/ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
long tempLength; /* Length variable x/ 
long tempLenl, tempLen2; /* temporary length variables x/ 
char cloneShare[] = "cloneShareQQ"; /* Base cloning share filename */ 
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long count; /* Number of bytes read in from file */ 
decimal(15,5) shareParm; /* Packed 15 5 var used for converting */ 
/* from packed 15 5 to binary. Numeric */ 
/* parms on iSeries are passed as dec 15 5x/ 


FILE «fp; /* File pointer x/ 
if (arge < 5) /* Check number of parameters passed in */ 
{ 


printf("Need Share index, Receiver name, SA name, and cert\n"); 
return 1; 


} 


/* Convert the packed decimal 15 5 parm */ 
/* to binary. */ 
memcpy (&shareParm, argv[1],sizeof(shareParm) ); 
shareIdx = shareParm; 
memset(name,' ',64); /* Copy the Private key name parm to a~ */ 
memcpy (name,argv[2],strlen(argv[2])); /* 64 byte space padded var. */ 
memset (SAname,' ',64); /* Copy the Share Admin name parm to a */ 
memcpy (SAname, argv[3],strlen(argv[3]));/* 64 byte space padded var. */ 


fp = fopen(argv[4],"rb"); /* Open the file containing the token x/ 
if (!fp) 
{ 


printf("File %s not found.\n",argv[4]); 


return 1; 
} 
memset (token,0,2500) ; /* Read the token from the file */ 
count = fread(token,1,2500, fp); 
fclose(fp); /* Close the file */ 
/* Determine length of token from length */ 
/* bytes at offset 2 and 3. */ 
token_len = ((256 * token[2]) + token[3]); 
if (count < token_len) /* Check if whole token was read in */ 
{ 
printf("Incomplete token in file\n"); 
return 1; 


} 


[RRR KKK AKER A KKK A KK AK KKK KKK KK KKK KEK KKK IKEA KIER KEE A KEKE | 


/* Find the certificate offset in the token */ 
/* x/ 
/* The layout of the token is */ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x/ 
/* x/ 


[RRR KKK KKK KK EKA K KKK KEK KKK KKK KKK KKK KA KK KAKI RAKE AKER KK | 


pub_sec_len = ((256 * token[10]) + token[11]); 
offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate section */ 

/* length from the length bytes at */ 

/* offset 2 of the section. */ 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 


[RRR K KER AKER AKER IKKE AK KEK AKER AK KER AKER AKEEKRKREEK | 

/* Open and read the clone file x/ 

[ REKRK ERK A KER AK RKEAK KEK AREA AKER KKK A KERR | 
/* Build path name from the base x*/ 
/* file name and the index */ 
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if (shareIdx < 9) cloneShare[11] = '0' + shareldx; 


else 
{ 
cloneShare[10] = '1'; 
cloneShare[11] = 'Q' + shareIdx - 10; 
} 
fp = fopen(cloneShare,"rb"); /* Open the file with the share 
if (!fp) 
{ 


printf("Clone share file %s not found.\n",cloneShare) ; 
return 1; 


} 
/* Read in the length of the KEK 
count = fread((char*) &cloneInfoKeyLength,1,4, fp) ; 


if (count < 4) /* Check if there was an error 
{ 
printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 
fclose(fp); 
return 1; 


} 
/* Read in the Key encrypting key 
count = fread((char*)cloneInfoKkey,1,cloneInfoKeyLength, fp) ; 


if (count < cloneInfoKeyLength) /* Check for an error reading 
{ 
printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 
fclose(fp); 
return 1; 


} 


/* Read in the length of the clone info 
count = fread((char*)&cloneInfoLength,1,4, fp); 


if (count < 4) /* Check for an error 
{ 
printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 
fclose(fp); 
return 1; 


} 


/* Read in the clone info 
count = fread((char*)cloneInfo,1,cloneInfoLength, fp) ; 


if (count < cloneInfoLength) /* Check for an error 
{ 
printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 
fclose(fp); 
return 1; 


} 
fclose(fp); /* Close the file 


[RRR KKK KKK AK ERIK KKK KEK AKER KER AKKEA KK A IKEA KEKE AK EERK KE | 


/* Install the share */ 


[RRR KKK KKK A KKK AK KK KKK KK KKK KKK AK KAKA A KKK AKER AK KEKK KE | 
memcpy ((void*)rule_array,"INSTALL ",8); /* Set rule array 
rule_array_count = 1; 


CSUAMKD( &return_code, &reason_code, &exit_data_length, 
exit_data, 
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*/ 


*/ 


*/ 


&rule_array_count, 
(unsigned char*)rule_array, 
&shareldx, 

name, 

SAname, 
&cert_sec_len, 
&token[offset], 
&cloneInfoKeyLength, 
cloneInfokey, 
&cloneInfoLength, 
cloneInfo); 


if (return_code > 4 ) 


{ 


printf("Master Key Distribution Failed : return reason %d/%d\n", 


return_code, reason_code) ; 


return 1; 


} 


else 


printf("Master Key share %d successfully installed.\n",shareldx) ; 
printf("Return reason codes %d/%d\n", return_code, reason_code); 
return 0; 


} 
} 


Example: ILE RPG program for installing a master key share 
Change this program example to suit your needs for installing a master key share. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DARK RKKAKK KK KEK KKK KEK KKK ERK KKK KKK KER KEK KEK KEK RRR RK KR RRR RR ERR KERR 


Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 


PUTSHARE 


Sample program to install a master key share as part of 
the master key cloning process. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these programs. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: Share number 
Name of share receiver private key 
Name of certifying key 
Path name of stream file containing sender certificate 


Example: 
CALL PGM(PUTSHARE) PARM(2 RECVR SAKEY SENDER. PUB) 


Use these commands to compile this program on iSeries: 
CRTRPGMOD MODULE(PUTSHARE) SRCFILE(SAMPLE) 
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D* CRTPGM PGM(PUTSHARE) MODULE (PUTSHARE) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

Dx Note: Authority to the CSUAMKD service program 
Dx in the QCCA library is assumed. 

Dx« 


Dx« 

DAK RRKKKKKKK KER KEK KEK KKK KERR KKK KEK KKK ERK KERR KK KER KEK RRR KKK ER RRR 
Peecescesessecsecesoe ase sec cseesseecsS ec ecsscossesscSsesscs 

D* Declare variables used by CCA SAPI calls 

Peeseseeeecee see e eee sent e ecco eee Sf cee eee eee See See see 

Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

D* ** Exit data length 

DEXTTDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Token length 

DTOKENLEN S 9B @ INZ(2500) 

D* ** Token and array for subscripting 

DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

Dx ** Private key name 

DPRVNAME S 64 

Dx «x Certifying key name 

DCERTKEY S 64 

Dx« 

DLSTRUCT DS 

D* ** Clone KEK length - one is binary form and the 
Dx *x other is used for reading the value from a file 
DCLONEKEKL 9B @ INZ(500) 

DCLONEKEKLC 1 4 

Dx ** Clone info length - one is binary form and the 
D* *x other is used for reading the value from a file 
DCLONEINFOLEN 9B © INZ(400) 

DCLONEINFOLENC 5 8 

D* ** Cloning key-encrypting-key 

DCLONEKEK S 500 

D* ** Cloning info 

DCLONEINFO S 400 

Dx ** Share index 

DSHAREIDX S 9B 0 

D« ** Data structure for aligning 2 bytes into 
Dx **x a2 bytes integer 

DLENSTRUCT DS 2 

DMSB il 1 

DLSB 2 2 

DLENGTH 1 2B 0 

D* *x Certificate section length 

DCRTSECLEN S 9B 0 

Dx ** Public key section length 

DPUBSECLEN S 9B 0 

Dx ** Index into Token array 

DTKNINDEX S 9B 0 

Dx ** Number of bytes to read from a file 
DINLEN S 9B 0 

D* ** File descriptor 

DFILED S 9B 0 

D« ** File path and length 
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D* The Common Cryptographic Architecture (CCA) verbs used is 
D* Master_Key Distribution (CSUAMKD). 


DPSTRUCT DS 


DPATH 80 INZ(*ALLX'00') 

DSIDX 11 12B 0 

DPATHLEN S 9B 0 

Dx ** Open Flag - Open for Read only 

DOFLAGR Ss 101 @ INZ(1) 

Dx ** Base name of file to store cloning share 
DSHAREFILE S 12 INZ('cloneShared0') 

Dx 


DARK AK KARR KKK ERK KEKE KK KK ERK KKK KKK KK R KEK RRR KEK KER ER KERR ERR KR EKER 


D* Prototype for Master_Key Distribution (CSUAMKD) 


DA KRKKKKKKKK KER KK KKK KK KERR KERR KK KERR RRR RRR RRR RRR ER KERR RRR 


DCSUAMKD PR 

DRETCOD 9B 0 

DRSNCOD 9B 0 

DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DSHRINDX 9B 0 

DKYNAM 64 

DCRTKYNAM 64 

DCRTL 9B 0 

DCRT 2500 OPTIONS (*VARSIZE) 
DCLNKEKL 9B 0 

DCLNKEK 1200 OPTIONS (*VARSIZE) 
DCLNL 9B 0 

DCLN 400 OPTIONS (*VARSIZE) 
Dx« 


DA KRAK KKK KKK KEK KKK ERK KK ERK KKK KERR KEKE KEKE KEK KEKE RRR RRR K KK ERRERE 


D* Prototype for open() 


DA KRKK KKK KKK KER KK KKK KKK E RRR RRR KEK KERR RRR ERR KKK ER KERR RRR ER ERR 
Dx value returned = file descriptor (0K), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B 0 VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 


DA RRA KKK KKK KEK KKK KKK KKK KEK KKK KKK KEK KK RRR KERR RRR KK ERK RRR RK KK ER KERR RER ERE 


D* Prototype for read() 


DA KRRKKKKKKK KER KKK KK KK KERR KER KEK K RRR ERR RRR RRR R KERR ERK RR ERREER 
Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
D« File descriptor returned from open() 

D 9B @ VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
D* Length of data to be read 

D 9B @ VALUE 

Dx« 


DARK AKKKKK KK KEK KKK KKK KKK RK KKK KK KKK KKK RE RK RRR KER KK ERK RRR KEKRER ER RERER ERE 
D* Prototype for close() 

DARK RK KARR KK KEK KKK KEK K KK KKK KKK KK KKK KKK RRR K RRR RR KK ERK RRR RER KERR RER ERE 
Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

Deeeeeee Soe ess ec eece eee scees cee ele Sete te eee eee eee ce see esl ess] 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

D¥eeescceess se ccscesceeee cess eccce ee esc ccc ec eee eee cesses ese 
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DMSG S 75 DIM(7) CTDATA PERRCD(1) 

D DS 

DMSGTEXT 1 80 

DSAPI 1 7 

DFATLRETC 4l 44 

DFATLRSNC 46 49 

DMSGLENGTH S 9B © INZ(80) 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ny 

DMSGTYPE S 10 INZ('*INFO ") 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B © INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx 

CR KKK KKK EK KKK KEKE KKK KER KEK ER ERK EKER KERR EK ERR ER ERK RR EK ERE RR EKER 
Cx START OF PROGRAM * 
Cx * 
Cc *ENTRY PLIST 

C PARM SINDEX 15 5 
C PARM PRVKEY 32 
C PARM SAKEY 32 
C PARM FILEPARM 32 
CR KKK KK KEKE KKK KKK EK KKK ERR RR EKER KKK ER KERR ERE RR EKER KERR EK ERE ERE KERR 
Cx Open certificate file 

CR KKK KKK KEK KKK KKK KKK KEK KKK ERE KKK KEK KKK RK KERR EK ERR RK ER ERE RR EKER E 
Cx* issccascceccsonhocsae= * 

Cx  »** Build path name * 

C* at ca oa a a * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 

C PATHLEN SUBST FILEPARM: 1 PATH 

Cx tweceeeesee sees eeseeces * 

Cx »* Open the file * 

Cx Fessoseeeseeseeeseses] * 

C EVAL FILED = open(PATH: OFLAGR) 

Cx Sweceeseeeseeseeeeee ees * 

Cx  »* Check if open worked * 

C* ec sa a a sms hs ree * 

C FILED IFEQ -1 

Cx HeseSssssseeussessessosecssossossesee * 

Cx * Open failed, send an error message * 

Cx eves sscsscceeseosessceslessss sosscce * 

C MOVEL MSG (1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx* 

C ENDIF 

Ce Fess sestete asian Sateee ese se seee cee setesee eases eeeeesee * 
Cx * Open worked, read certificate from file and close file * 
Cx Ce ee ee ee ee eee * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

C* 

Cx eels seSsee se oseo ae Sas aeae aaa - SSeS eae * 

Cx * Check if read operation was OK * 

Cx MeSee senses as See ea = ae eaee ae sae eae * 

C TOKENLEN IFEQ -1 

C MOVEL MSG (2) MSGTEXT 

C EXSR SNDMSG 

C ENDIF 

Cx 

Ce Fiske seeeeeeeesesteces acess este seeeee es * 

Cx * Check if certificate length is valid * 

Cx * The length bytes start at position 3 * 

Cx* Vesa wacaeeeeossetacoocssaeecceecsecsecs * 
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C EVAL MSB = TOKENARRAY (3) 

C EVAL LSB = TOKENARRAY (4) 

C LENGTH IFLT TOKENLEN 

Cx (La Kose ce See eee ee Relea eee * 

Cx * Certificate length is not valid * 

Cx« Loss nacwooneeeaesesoSeeseeuesocesas * 

C MOVEL MSG (3) MSGTEXT 
C EXSR SNDMSG 

C RETURN 

C ENDIF 


Cx« 

CR KKK KK KKK KKK KEKE KR EKER KER ERK KK EKER KER KEK ERR EKER KERR EKER KERR ERR ERE 
Cx Find the certificate in the token 

Cx« 

Cx The layout of the token is 

Cx* 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at position 2 (11 overall) 
Cx - Private key name - 68 bytes 

Cx - Certificate section 

Cx* 

Cx Note: 1 is added because RPG arrays start at 1. 

CR KKK KK KEKE KKK KEKE KR KEKE KK EK ERK KKK KER RK KEK KERR ER ERK RR ER ERK ERRERE 


C EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
Cx« 

Cx« Lisstessoacunsesea os sasecscesosscssece cess * 

Cx * Determine length of certificate section * 

Cx * Length bytes are at position 2 of the * 

Cx * section. 

Cx« (aeeeceeseacsaas SeesesosSseeoeoeesoeceeee = * 

C EVAL MSB = TOKENARRAY(TKNINDEX + 2) 
C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 
C EVAL CRTSECLEN = LENGTH 

Cx* 


CR KK KKK KEKE KKK KEKE KR KEKE KK EK ERE KK EKER RRR RK ERR EKER KERR EKER RR ER 


Cx Open and read the clone file 
CR KKK KKK EKA K KEKE KR ERE RK ER ERE KK RK EKER KEK ERR ER ERE RR ER ERRERRER 


Cx* Ge saa a i is a li el la an * 

Cx »* Set share index number * 

Cx «* (Convert from packed 15 5 to binary) * 

Cx« twecsecooesacesaeseacscesencouscaseacsooskess * 

C Z-ADD SINDEX SHAREIDX 

Cx ** Build path name 

C MOVEL *ALLX'00' PATH 

C MOVEL SHAREFILE PATH 

Cx «x Adjust two digits on file name by adding to their 
Cx ** character value 

C SIDX ADD SHAREIDX SIDX 

Cx ** If the index is greater than or equal to 10 
Cx ** then add 246 to force the first character to change 
C SHAREIDX IFGE 10 

C SIDX ADD 246 SIDX 

C ENDIF 

Cx 

Cx ** Open the file 

Cx* 

C EVAL FILED = open(PATH: OFLAGR) 
Cx« 

Cx ** Check if open worked 

Cx* 

C FILED IFEQ -1 

Cx* 

Cx ** Open failed, send an error message 

Cx« 
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C MOVEL MSG(4) MSGTEXT 


C EXSR SNDMSG 

C* 

C ELSE 

Cx* 

Cx ** Qpen worked, read in the clone information and close file 

C* 

C SETON 01 
C Z-ADD 4 INLEN 

C EVAL INLEN = read(FILED: CLONEKEKLC: INLEN) 

Cx* 

C* asa seco concen eee sac ee eeme esse nee eee * 

Cx * Check if read operation was OK * 

Cx* Css oasaceneeesanacoee le eeeeeecetooeese * 

C INLEN IFNE 4 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

C* 

C «61 EVAL INLEN = read(FILED: CLONEKEK: CLONEKEKL) 
C* 

C  OLINLEN IFNE CLONEKEKL 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

Cx* 

C «(Ol Z-ADD 4 INLEN 

C «(61 EVAL INLEN = read(FILED: CLONEINFOLENC: INLEN) 
C* 

Cx* fans scetosteaenee acon aaseacewceeee eee * 

Cx * Check if read operation was OK * 

Cx* LKeowecaconeansacoseases= aesecesatooaeoe * 

C  O1INLEN IFNE 4 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

(7 

Cc “01 EVAL INLEN = read(FILED: CLONEINFO: CLONEINFOLEN) 
C* 

Cx* a ceecsee sacs eeseee seas sae Sece=aeeeesee * 

Cx * Check if read operation was OK * 

C* (ase saSeeseakasena mec eeece eee e eeeeece * 

C  OLINLEN IFNE CLONEINFOLEN 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

C* 

C CALLP close (FILED) 

C NOL SETON LR 
C* 


CR KKK KKK EK KKK RK EK RE KER KER ERE RK RK ER KERR EKER ER ERE RR EK ERE RR EKER 


Cx Obtain a certificate 
CR KKK KKK KEK KKK EKER RK K EKER KEKE KK RK ER KEK KKK ERR EK EKER KEK ERE RRR EK 


Cx toeeeSesaesessee ses aasassassseese = sasseas= * 

Cx  »* Set share index number * 

Ce Cese ae eeoceee seach ese een ese sce eee se eet eeses * 

C Z-ADD SINDEX SHARE IDX 

Cx Yeeiessscssseee sss secesosscssecssssesesosse * 

Cx »* Set private key name * 

Ce hese soe se eeeetee eesti eerie eee See se ee cee eS * 

C EVAL LENGTH = %LEN(%TRIM(PRVKEY) ) 
C LENGTH SUBST PRVKEY:1 PRVNAME 

Cx FSslesSsssssssceseless cose SsSelossssssoosec * 
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Cx »* Set certifying key name 


Cx* Ce aseceaiak see eseteceeeeee oe seee eee eceue * 

C EVAL LENGTH = %LEN(%TRIM(SAKEY) ) 
¢ LENGTH SUBST SAKEY:1 CERTKEY 

Cx Kosessssscsesesscsssoscsssessesoussscsccscesu * 

Cx »* Set the keywords in the rule array * 

Cx* ee ee * 

C MOVEL "INSTALL ! RULEARRAY 

¢ Z-ADD i RULEARRAYCNT 
Cx« Kesessc ssc ssscsssscssssscsssesocsssse 

Cx »* Call Master Key Distribution SAPI 

Cx« a ee ee ee 

C CALLP CSUAMKD (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C SHAREIDX: 

C PRVNAME : 

C CERTKEY: 

C CRTSECLEN: 

C TOKENARRAY (TKNINDEX) : 
C CLONEKEKL: 

C CLONEKEK: 

C CLONEINFOLEN: 
C CLONEINFO) 
(a ee eee ee 

Cx * Check the return code 

Ck Sescecesooseasses-ssceas 

C RETURNCODE IFGT 4 

Cx* cme nsa nea e name eenae aimee! * 

Cx * Send failure message * 

Cx* tissscsesectesascesasaas * 

C MOVEL MSG (6) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSUAMKD' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx Hace sao seen aoa e aoa aa aie: * 

Cx * Send success message * 

Cx« eee oe eee oe * 

C MOVEL MSG(7) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 32: 12) = 

C %SUBST(PATH: 1: 12) 
C EXSR SNDMSG 

C ENDIF 

Cx* 

¢ SETON LR 
Cx 


CK KK KKK KKK KKK KEK RK KEK KEK ERK KK EKER KEK KEKE KR EKER KERR ERE KERR ERR 


Cx Subroutine to send a message 
CR KKK KK KEKE KKK KEKE KKK KER KER ERE KK RK EKA R KEKE RR ER ERE RRR ERK RR ERR 


C SNDMSG BEGSR 
CALL 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
ENDSR 


SSeS SZSSSSZSZz 


OOOO OA WO: Oo: 


"QMHSNDPM! 


MESSAGEID 
MESSAGEFILE 
MSGTEXT 
MSGLENGTH 
MSGTYPE 
STACKENTRY 
STACKCOUNTER 
MSGKEY 
ERRCODE 
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Cx 
K* 
The certificate file could not be opened. 
There was an error reading from the certificate file. 
The length of the certificate is not valid. 
The clone share file could not be opened. 
The clone share file either could not be read or has invalid data. 
CSUAMKD failed with return/reason codes 9999/9999. 
The share was successfully installed. 


Example: ILE C program for listing retained keys 
Change this program example to suit your needs for listing retained keys. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287| for 


important legal information. 


ff hese aeees ease eee cee seetenessecer ea asesee See eee sere sassseeeseoessece «/ 
/* List the names of the RSA private keys retained within the */ 
/* 4758. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 x/ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. x/ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(LISTRETAIN) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. x/ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Access Control Initialization (CSUAACI). */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(LISTRETAIN) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(LISTRETAIN) MODULE(LISTRETAIN) */ 
/* BNDSRVPGM(QCCA/CSNDRKL) */ 
/* x/ 
/* Note: Authority to the CSNDRKL service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Retained Key List (CSNDRKL). */ 
/* x/ 
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#include <string.h> 
#include <stdio.h> 
#include "csucincl.h" 


void main(void) 


{ 
[Resceseeerseeseka Sees Seeese sense pe eeesetesee neces ae sseoe ss 
/* standard CCA parameters 

[iss deseo Saesee nso saaeae ee a Sosa] See eee aaa eee eas aes eeS 
long return_code; 

long reason_code; 

long exit_data_length; 

unsigned char exit_data[2]; 

long rule_array_count; 


unsigned char rule_array[2] [8]; 


unsigned char key_label_mask[64]; 
unsigned char key_label [500] [64]; 


long retain_key_count; 

long key_label_count = 500; 

int ks 

[kos ceeee see ssa seen e te eee ss ees eases eee = eee Soe see See eee 
/* Set up label mask, ie. which key name to retrieve. 

/* *.*.*.*.*.*,* 1S a wildcard for all keys. 
[#escessessasassscescusssecsscocssecesseseassecsseesssessecee 
memset (key_label, 0x00, sizeof(key_label) ); 

memset (key_label_mask, ' ', sizeof(key_label_mask)); 

memcpy (key_label_mask,"*.*.*.*.*.*.*", 13); 


rule_array_count = 0; 


CSNDRKL(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
key_label_mask, 
&retain_key_count, 
&key_label_count, 
(unsigned char*)key_label); 


if (return_code != 0) 


printf("Retained Key List failed with return/reason %d/%d \n", 


return_code, reason_code) ; 
return; 


else 


printf("Retained key count [%d]\n",retain_key_count) ; 


printf( "No. of key labels returned [%d]\n",key_label_count) ; 


if (key_label_count > 0) 
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*/ 


nese */ 


ts laa */ 


*/ 


Smears */ 


Ane */ 


*/ 
*/ 


cuwoee «/ 


siediasiaieaes «/ 


*/ 


meee «/ 


imine */ 


*/ 


sce */ 


a «/ 


*/ 
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/* Display the names of each key returned. */ 


printf("Retain list = \n" ); 

for (k = 0 ;k < key_label_count; k++) 
{ 
printf( "[%.64s]\n",key_label[k]); 


} 
} 
} 


Example: ILE RPG program for listing retained keys 


Change this program example to suit your needs for listing retained keys. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287|for 


important legal information. 


DA KRRKKKK KKK KEK KEKE KKK KERR KKK RRR RRR ER KER KERR KERR RRR KEKE REE EKER 
Dx 

Dx List the names of the RSA private keys retained within the 
Dx 4758. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

D* Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx« 

Dx Example: 

D* CALL PGM(LISTRETAIN) 

Dx« 


D* Use these commands to compile this program on iSeries: 

D* CRTRPGMOD MODULE(LISTRETAIN) SRCFILE(SAMPLE) 

D* CRTPGM PGM(LISTRETAIN) MODULE(LISTRETAIN) 

Dx BNDSRVPGM(QCCA/CSNDRKL) 

Dx« 

D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Retained_key List (CSNDRKL) 


Dx« 

Dx Note: Authority to the CSNDRKL service program in the 

Dx QCCA library is assumed. 

Dx« 

Dx« 

D* Note: This program assumes the card with the profile is 

Dx already identified either by defaulting to the CRPOQ1 
D* device or by being explicitly named using the 

D* Cryptographic_Resource Allocate verb. Also this 

D* device must be varied on and you must be authorized 
Dx to use this device description. 

Dx« 

DAKAR KKK KKK KK ERK KEKE KKK KERR KERR R KKK ERE RRR KK RRR KERR KEKE REE RRR 
Pease teae eee eS eee eee eee ee ee eee ese ee ee Sees See Se 


D* Declare variables for CCA SAPI calls 
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Dx ** Return code 
DRETURNCODE S 9B 0 
Dx ** Reason code 
DREASONCODE Ss 9B 0 
Dx ** Exit data length 
DEXITDATALEN S 9B 0 
Dx ** Exit data 
DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT Ss 9B 0 
Dx ** Rule array 
DRULEARRAY S 16 

Dx ** Key label mask 
DKEYLBLMASK S 64 

Dx ** Key count 
DKEYCOUNT S 9B 0 
Dx ** Label count 
DLABELCOUNT S 9B 0 
Dx ** Label list and label array 
DLABELLIST DS 3200 
DLABELS 64 DIM(50) 
Dx ** Loop counter 

DI S 9B 0 
Dx« 


DA RRKKKKKKKK KEK KKK KEKE KERR RRR K KEK K KERR RRR RRR RR ERR KR ER KKK ERERE 


D* Prototype for Retained Key List 


DARK RKKKKK KK KER KKK EK KKK ERK KKK KKK KEKE RK KKK KKK KER KEK RRR KKK ERE 


DCSNDRKL PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DKYLBLMSK 64 

DKYCOUNT 9B 0 

DLBLCOUNT 9B 0 

DLBLS 64 

Dx« 

Dee eee ene eee ecole ese ce ace sees eee eee ae ese eee eee See eee 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
DPkeSeceScSssssscoscuseeeSsssssesssceeseosessesscslSeseeeeseesasc] 
DMSG S 75 DIM(4) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DNUMKEYS 1 3 

DNUMLABELS 25 26 

DDSPLBL 2 65 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S vi INZ(' ") 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY Ss 4 INZ(' ') 

DMSGTYPE Ss 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B © INZ(OQ) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR K KK KK KKK KKK KEKE KR EKER KER ERK KK EKER KERR ERE RR EK ERR RR ERE REE ERR 
Cx START OF PROGRAM * 
Cx« * 
CxSecescosscteccsecas oases seseccecc fees loa SsseseSssceS esse sees * 
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Cx No rule array keywords 


CXeeSSseesceees eee sere sees eee See Ses sees sees ee alos cess scs 
C Z-ADD 0 RULEARRAYCNT 
CXeeesseceeceseeeseesse sees eee b esl eee ee ee ees 
Cx Get up to 50 labels 
CxkeceestecsessecescesscsSessesSsesoes assess cacesistSeusscu secs 
C Z-ADD 50 LABELCOUNT 

Ckste cece ce cece ses e ese eee see cee ee ese eee Seer eee eee oe ece st oeees 
Cx Set the mask to everything 
ee eee ea 
Cc MOVEL ‘x! KEYLBLMASK 

CkXseSeeo- po eee eee eee ee See Sol eee ceceen abe sc oesscs 
Cx Call Retained Key List SAPI 
(CxkSceeSSsscescstecsessessesscseSssece sol eScesssscessceces cusses 
C CALLP CSNDRKL (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 

C RULEARRAY : 

C KEYLBLMASK: 

C KEYCOUNT: 

C LABELCOUNT: 

C LABELLIST) 

(Xeno eee eee eee see see eee * 

Cx Check the return code * 

Ctecseeeseesesssseeansees * 

C RETURNCODE IFGT 4 

Cx Pesesosseasesssssoeesse * 

Cx * Send error message * 

Ce Fesse sees sesso e se eee ce * 

C MOVE MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Ce 

C ELSE 

C* 

Cx eesSScosesseseces ssesee * 

Cx * Check number of keys * 

C# Hesesesseesseeeeeeceecs * 

C LABELCOUNT IFEQ 0 

Cx heeesesaseas= ssl 2sees—e=s——eSse— se seecs— * 

Cx * Send message saying there are no keys * 

C* Se tas i es atm Ss, ae he pp ms ee a * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx 

C ELSE 

Cx* 

Cx Keser os Seeseshe sess esse eee eee eee * 

Cx * Send message with number of keys * 

Cx Hosmseeeeesa=se-saoeeassaeeses=ese— * 

C MOVE MSG (3) MSGTEXT 

C MOVE KEYCOUNT NUMKEYS 

C MOVE LABELCOUNT NUMLABELS 

C EXSR SNDMSG 

C* 

Ce Wessee sees tose e seca ese ese eeee tee * 

Cx * Display each key label up to 50 * 

Cx Kaeo se Soeaas=ssseSeaSeoeaseseaseose * 

C MOVE MSG (4) MSGTEXT 

C FOR I=1 BY 1 TO LABELCOUNT 

C MOVEL LABELS (1) DSPLBL 

C EXSR SNDMSG 

C ENDFOR 

Cx* 
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** 


C ENDIF 


C ENDIF 
Cx* 
C SETON 
Cx« 


LR 


CR R KK KKK E KK KKK KERR KEKE KK KK ERK KK EKER KERR EKER ERE RK RR ER ERE RR ERR ERE 


Cx Subroutine to send a message 
CR KKK KK KKK KKK KEKE KR EKER KER ERK KK RK EKER KEK ERR ER ERR RR ERE RRR ERR ERE 


C SNDMSG BEGSR 
CALL 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
PAR 
ENDSR 


SSS SS SSS 


OOOO O:30O:0: 7 


"QMHSNDPM! 

MESSAGEID 
MESSAGEFILE 
MSGTEXT 
MSGLENGTH 
MSGTYPE 
STACKENTRY 
STACKCOUNTER 
MSGKEY 
ERRCODE 


CSNDRKL failed with return/reason codes 9999/9999 
There are no retained keys in the 4758 
000 keys were found and 00 labels returned 


[ 


] 


Example: ILE C program for deleting retained keys 
Change this program example to suit your needs for deleting retained keys. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Sone hicee eee eee ee ee SR eel lial «/ 
Delete a retained key from the 4758 x/ 
* 

/ 

*/ 

COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 */ 
* 

/ 

This material contains programming source code for your x/ 
consideration. These examples have not been thoroughly */ 
tested under all conditions. IBM, therefore, cannot */ 
guarantee or imply reliability, serviceability, or function */ 
of these program. All programs contained herein are x/ 
provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


these programs and files. x/ 
* 

/ 

x/ 

Note: Input format is more fully described in Chapter 2 of */ 
IBM 4758 CCA Basic Services Reference and Guide x/ 
(SC31-8609) publication. */ 

* 

/ 

Parameters: x*/ 
none. */ 
x/ 

Example: */ 
CALL PGM(DLTRTNKEY) (SSLPRIV.KEY.ONE) x/ 

* 

/ 

x/ 

Note: This program assumes the card with the profile is x/ 
already identified either by defaulting to the CRPO1 */ 
device or by being explicitly named using the */ 
Cryptographic_Resource Allocate verb. Also this x/ 
device must be varied on and you must be authorized */ 

to use this device description. x*/ 

* 

/ 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 


#i 
#i 


#d 
#d 


vo 


{ 


/ 


The Common Cryptographic Architecture (CCA) verb used is 


Retained Key Delete (CSNDRKD) . 


Use these commands to compile this program on iSeries: 


ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(DLTRTNKEY) SRCFILE(SAMPLE) 

CRTPGM PGM(DLTRTNKEY) MODULE(DLTRTNKEY) 
BNDSRVPGM(QCCA/CSNDRKD) 


Note: Authority to the CSNDRKD service program in the 
QCCA library is assumed. 

nclude <string.h> 

nclude <stdio.h> 

nclude "csucincl.h" 

standard return codes 

efine OK 0 
efine WARNING 4 

id main(int argc, char * argv[1]) 
[MaSeeeeecassas cease essasassess so5Ss5a4s Ss 5seooasoesseeees le 
/* standard CCA parameters 
/RocestSeessseesee ease hese sesso eeeosh bese ee ceo ee eeee 
long return_code; 

long reason_code; 

long exit_data_length; 

unsigned char exit_data[2]; 

long rule_array_count = 0; 


unsigned char rule_array[1] [8]; 
unsigned char key_label[64]; 


if (argc < 1) 
{ 
printf("Key label parameter must be specified.\n"); 
return; 


Keene eee 


memset(key_label, ' ', 64 ); 
memcpy(key_label, argv[1], strlen(argv[1]) ); 
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CSNDRKD(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
key_label); 


hardware 


eendems «/ 


*/ 


if ( (return_code == OK) || (return_code == WARNING) ) 


printf("Request was successful\n"); 
returns 


} 


else 


printf("Request failed with return/reason codes: %d/%d \n", 
return_code, reason_code); 
returns 


} 


} 
Example: ILE RPG program for deleting retained keys 


Change this program example to suit your needs for deleting retained keys. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


DA KRAKKKKKKK KEK KKK KEK KKK ERK KKK KKK KER RK KEK KEK RRR RK KR ERK RR ERR RRR 
D* DLTRTNKEY 

Dx« 

D* Sample program to delete a retained key from the 4758 

Dx 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx 


D* Parameters: 
Dx Retained key label name 


Dx (64 chacters - pad with blanks on the right) 
Dx« 

D* Example: 

Dx« 


D* CALL DLTRTNKEY + 

D* 'PKA.RETAINED.KEY.123 ; 
Dx« 

D* Use these commands to compile this program on iSeries: 

D* CRTRPGMOD MODULE(DLTRTNKEY) SRCFILE(SAMPLE) 

D* CRTPGM PGM(DLTRTNKEY) MODULE (DLTRTNKEY) 


D« BNDSRVPGM(QCCA/CSNDRKD) 

Dx 

D* Note: Authority to the CSNDRKD service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Retained_Key Delete (CSNDRKD) 
Dx« 
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DA RRA KKK KKK KER KKK KERR KKK RK KKK KEK KKK RRR KKK KKK RRR KE KR R KERR RRR RKRERE 


[De ee ee ee ee 

D* Declare variables for CCA SAPI calls 

Pee Sasa t ease ase ce eee eeeiee eect see see Sessa 

Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx xx Exit data length 

DEXITDATALEN S 9B 0 

D« «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Retained key label 

DKEYNAME S 64 

Dx« 

DARK RK KK KKK KK ER KKK KEK KKK KKK KEKE KK RK ERK KKK KEK RRR RRR RRR KKK ERERK 

D* Prototype for Retained_Key Delete (CSNDRKD) 

DA RRR KKK KKK KERR KEKE KKK RRR KK RRR KKK REE RK RR KER RRR RRR ER KER RERERRERK 
DCSNDRKD PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DKEYNAM 64 

Dx« 

P¥eesseeesoSs secon sestesee aloe sees este esse esac Ses S oe SSeS sce= 
Dx *x Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

[OE ee ee a ee 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B @ INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILMSGTEXT 1 50 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' M) 
DMESSAGEFILE 5 21 INZ(' 

DMSGKEY S 4 INZ(' t) 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR KKK KKK KKK KK KK ERR KK ERK KK ERE KK RK ER KEK KKK ERR EK ERE RR EKER ERR EKER EK 
Cx START OF PROGRAM * 
(3 * 
C *ENTRY PLIST 

C PARM KEYNAME 

C* * 
Cksceesseseescces ees oeeetees see see Sse ece Seep tee ee ee esas ses ee * 
Cx Set the keywords in the rule array * 
(CXsaeeeSesSceee see sease Soo ae se Sea eas SSS Sessa eee sass ase esse a= * 
C Z-ADD 0 RULEARRAYCNT 
ee a er eee * 
Cx Call Retained Key Delete SAPI * 
Ckeeeecs ee eca ee eec seen see S se cesses eee ee Seabee see eS eee ses * 
C CALLP CSNDRKD (RETURNCODE: 

C REASONCODE: 
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C EXITDATALEN: 
C EXITDATA: 

€ RULEARRAYCNT: 
C RULEARRAY : 

C KEYNAME) 
Cxsescsccesessccscssosecs * 

Cx Check the return code * 

CXeseeseewecescencescnccs * 

C RETURNCODE IFGT 4 

Cx tesa se easeasa=soeesee a= * 

Cx * Send error message * 

Cx* (acon eca cma a alana ames * 

C MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx 

C ELSE 

Cx* Ssacaacuncecasaaaceeeaee * 

Cx * Send success message * 

Cx* Se cs sc a ear * 

C MOVE MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx 

C ENDIF 

Cx 

C SETON LR 
Cx« 


CR KKK KKK KKK KK EKER RK KEK KEK ERK KK EKER KEK KEK KERR ERE RRR ERE KKK ERR ERE 


Cx Subroutine to send a message 
CR KKK KK KKK KKK KEKE KR EKER KER ERK KK RK EKER KEKE RR EKER KERR ERE REE ERR 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


** 


CSNDRKD failed with return/reason codes 9999/9999' 
The request completed successfully 


Troubleshoot the 4758 Cryptographic Coprocessor 


Use the methods below to tackle some of the basic problems that may occur with 
your 4758 Coprocessor. If the troubleshooting information does not address your 
problem, contact your service representative. 


Always assure that you have applied all current PTFs for the relevant products 
and programs. 


Using return codes 


The primary method for detecting and troubleshooting problems is by monitoring 
return codes and reason codes. 
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A return code of 0 indicates successful completion. To provide some additional 
information, the 4758 Coprocessor associates some non-zero reason codes with 
this return code. 


A return code of 4 indicates that the application programming interface (API) 
has completed processing, but an unusual event occurred. It could be related to 
a problem created by the application program, or it could be a normal 
occurrence based on data that is supplied to the API. 


A return code of 8 indicates that the API did not complete successfully. An 
application programming error most likely caused this. 


A return code of 12 normally indicates some type of problem in the setup or 
configuration of your 4758. This code means that the processing of the API did 
not complete successfully. 


A return code of 16 normally indicates a severe error in Common Cryptographic 
Architecture Cryptographic Service Provider (CCA CSP), iSeries licensed internal 
code, or the 4758 Coprocessor licensed internal code. For these types of errors, 
you should contact your service representative. 


You can also troubleshoot problems by analyzing the messages that appear in the 
job log or in the system operator (QSYSOPR) queue. Generally, any event that 
sends a message to the job log also returns an associated return code and a reason 
code to the calling programming. Messages sent to the system operator message, if 
reporting a severe problem, will normally point to a source of additional 
information about the problem. Such information is intended for IBM service, and 
therefore you may not necessarily find them useful for problem determination. 


Common errors 


You should watch out for these common errors: 


Have you installed the 4758 Coprocessor and the CCA CSP? The 2620 
Cryptographic Processor and 2628 Cryptographic Processor - Commercial are 
completely separate solutions that work with the IBM CCA Services for iSeries. 
The 4758 Coprocessor and CCA CSP will not work with the 2620, the 2628, or 
the IBM CCA Services. 


Did you vary on the device? You cannot send any requests to your 4758 
Coprocessor until you vary on the device. 


Is the resource for the cryptographic device description a 4758 Cryptographic 
Coprocessor or a 2620 or 2628? It should be a 4758 Cryptographic Coprocessor. 


Is the 4758 Coprocessor finding a device? If you do not explicitly use the 
Cryptographic_Resource_Allocate API, you must name the cryptographic device 
CRP01. If you do not name it that, the CCA cannot select any device. Either 
name the device CRPO1 or change your program to use the 
Cryptographic_Resource_Allocate CCA API to select the device. 


Are you selecting the correct device? If you have a default device (for example, 
a device named CRPO1) and an additional device, the 4758 Coprocessor will 
select the default device, unless you use Cryptographic_Resource_Allocate. 


Is the 4758 Coprocessor finding a key store file? If you do not explicitly use the 
Key_Store_Designate SAPI, the CCA CSP support will attempt to use the files 
named on the device description. If you have named no files on the device 
description, the 4758 Coprocessor will not find any files. 


Have you loaded and set a master key? The 4758 Coprocessor will not complete 
any cryptographic requests other than those for configuring your 4758 
Coprocessor, unless you load a master key. 
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* Does the Old master key register contain a key? The 4758 Coprocessor cannot 
re-encrypt keys under the Current master key unless the Old master key register 
contains a value. 


* Does your default role have authority to use a given hardware command? If 
not, you will need to log on by using a profile that uses a role that has the 
correct authority. 


* Does any role have authority to use a given hardware command? If your 4758 
Coprocessor requires the hardware command and you have not authorized a 
role to use that command, you must reinitialize your 4758 Coprocessor. Do this 
by using either the Cryptographic_Facility_Control API or the Hardware Service 
Manager that is found in System Service Tools. Using the 
Cryptographic_Facilty_Control API requires that you authorize a role to the 
hardware command that reinitializes the 4758 Coprocessor. If no such role exists, 
you must use the Hardware Service Manager. 


* Is a function control vector loaded? Your 4758 Coprocessor cannot run any 
cryptographic operations other than configuration until you load a function 
control vector. 


* Is one of the Cryptographic Access Provider products installed? IBM ships the 
function control vectors with these products. 


* If you are loading a master key, did you begin by clearing out the new master 
key register? If your 4758 Coprocessor has a partially loaded new master key 
register, you cannot load the first part of a master key. 


* Did you remember to set the clock in your 4758 before removing the authority 
to do so from the DEFAULT role? If not, you must reinitialize your 4758 
Coprocessor by using either the Cryptographic_Facility_Control API or the 
Hardware Service Manager found in System Service Tools. Using the 
Cryptographic_Facilty_Control API requires that you authorize a role to the 
hardware command that reinitializes the 4758 Coprocessor. If no such role exists, 
you must use the Hardware Service Manager. 


* Did you set the EID before trying to generate public-private key pairs? You 
must set the EID before you can generate RSA keys. 


* Did you correctly initialize the first byte of a null key token to binary 0? If 
not, the CCA support may try to use it as a key label. CCA Support will either 
report it as a bad label format or report that it could find the key record. 


* Do you use the same name for a label in a PKA key store file and a retained 
PKA key? If so, your 4758 Coprocessor will never find the retained key because 
the 4758 Coprocessor always searches the key store file first. 


* Do you have EBCDIC data in any fields in a skeleton PKA key token? The 
4758 Coprocessor specifically checks for ASCII data in a number of the fields 
and will return an error if it finds EBCDIC data. 

For further troubleshooting information, see|“Reinitialize the 4758 Cryptographic 

and |“Use the Hardware Service Manager” on page 278 


Reinitialize the 4758 Cryptographic Coprocessor 


If you set up your 4758 Coprocessor incorrectly, you can end up with an unusable 
configuration with which you cannot perform any cryptographic functions and 
cannot use any of the APIs to recover. For example, you can configure it such that 
you have no role authorized to set the master key and no role authorized to 
change or create new roles or profiles. 


You can call the hardware command for reinitializing the card by using the 
Cryptographic_Facility_Control (CSUACFC) SAPI. Two example programs are 
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provided for your consideration. One of them is written in ILE C, while the other 
is written in ILE RPG. Both perform the same function. 


* |“Example: ILE C program for reinitializing the 4758 Coprocessor” 


° |“Example: ILE RPG program for reinitializing your 4758 Coprocessor” on 
page 275 


Note: If you choose to use the program example that is provided, change it to suit 
your specific needs. For security reasons, IBM recommends that you 
individualize these program examples rather than using the default values 
provided. 


However, in some cases, there may not be a role that is authorized to any 
hardware command. In this case, you must reload the Licensed Internal Code by 


using the function that is provided in Hardware Service Manager in System 
Service Tools as described in |Use the Hardware Service Manager” on page 278 
Updating the Licensed Internal Code in the 4758 Coprocessor 


Loading the Licensed Internal Code in your 4758 Coprocessor erases the master 
key, all private keys, and all roles and profiles that are stored in your 4758 
Coprocessor. Because of this, the server does not automatically load PTFs for the 
Licensed Internal Code in the 4758 Coprocessor, and the PTFs always require 
action on your part to enable them. Before you load the Licensed Internal Code, 
take appropriate actions to ensure that you can recover, such as ensuring that you 
have a hard copy of your master key. 


Note: If you randomly generated your master key, you will need to clone that key 
into a second 4758 Coprocessor. If you do not, you will lose all your 
encrypted keys when you reinitialize your 4758 Coprocessor. 


Example: ILE C program for reinitializing the 4758 Coprocessor 
Change this program example to suit your needs for reinitializing your 4758 
Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


[xieeeescesasesaseess nese meson os nesses oe beee eee sees seesecesseesesese */ 
/* Clear the 4758 card (reset to manufactured state). */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 

/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: This verb is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
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/* Example: */ 
/* CALL PGM(REINIT) */ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 x/ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(REINIT) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(REINIT) MODULE(REINIT) BNDSRVPGM(QCCA/CSUACFC) x/ 
/* x/ 
/* Note: Authority to the CSUACFC service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Facilitiess Control (CSUACFC). */ 
/* x/ 
[Bases son sees sesestoassesssasesses eas eases esses sesse- eS ssce Sees ss «/ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries x/ 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


[eeecs nessa cenesesessesesaeeees==Se sae eeee Sea a sees ae sane=a>-eSeessesS */ 
/* standard return codes */ 
/ Peeneeceaseeesose sesso saeeescnee essen eoesr ese een cones ceeeseserseeceee */ 
#define ERROR -1 
#define OK 0 


#define WARNING 4 


#define TOKENSIZE 8 /* number of bytes in random token */ 


int main(int argc, char *argv[]) 


{ 


| a ee ee eee ee ea ee «/ 
/* standard CCA parameters x/ 
[Rose see assesses esassesoeseesseedeSssese he nesnseenes Sheer eeeeeeeeeee «/ 


long return_code = 0; 
long reason_code = 0; 
long exit_data_length 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count 


I 
ine) 
we 


I 
ine) 
we 


| Raeeeececisoe aaa a5 sasae nace sees as eeesas > Se ses ose sae seseeaseeeesaee «/ 


long verb_data_length = TOKENSIZE; 
char verb_data[TOKENSIZE] ; 

char verb_data2[TOKENSIZE] ; 

int is; 
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/* set keywords in the rule array */ 
memcpy (rule_array, "ADAPTER1RQ-TOKEN", 16) ; 
/* get a random token from the card - returned in verb_data x*/ 
CSUACFC( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
(char *)verb_data) ; 
if ( (return_code == OK) | (return_code == WARNING) ) 
{ 
printf("Random token was successfully returned. \n"); 
printf("Return/reason codes "); 
printf("%ld/%ld\n\n", return_code, reason_code); 
/* get the one's complement of token and store in verb_data2. */ 


/* operate on one byte at a time */ 


for(i = 0; i < TOKENSIZE; i++) 
{ 


verb_data2[i] = “verb _data[i]; 


/* change keyword in rule array */ 
memcpy (&rule_array[1],"RQ-REINT",8); 
/* invoke the verb to reset the card */ 
CSUACFC( &return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

(char *)rule_array, 


&verb_data_length, 
verb_data2); 


if ( (return_code == OK) | (return_code == WARNING) ) 
printf("4758 card successfully cleared/reset.\n"); 
printf("Return/reason codes "); 
printf ("%ld/%ld\n\n", return_code, reason_code); 
return(OK); 


} 


else 

{ 
printf("An error occurred while clearing the 4758 "); 
printf("card.\n Return/"); 


printf("reason codes %ld/%ld\n\n", return_code, reason_code); 


return (ERROR) ; 
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} 

else 

{ 
printf ( 
printf ( 
printf ( 


return( 


} 
} 


"An error occurred while getting the random token.\n"); 
"Return/reason codes "); 
"%1d/%ld\n\n", return_code, reason_code); 


ERROR) ; 


Example: ILE RPG program for reinitializing your 4758 
Coprocessor 


Change 


this program example to suit your needs for reinitializing your 4758 


Coprocessor. 


Note: Read the|Chapter 6, “Code disclaimer information” on page 287] for 


important legal information. 


D«x« 
Dx 
Dx 
Dx« 
Dx 
Dx« 
Dx 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx 
Dx 
Dx« 
Dx 
Dx« 


D«x« 


Dx 


KKKKKKKKKKEKRKE ERE KERR RRR RRR RRR RR KK KERR KERR KERR KR KK RRR RRR RRRERERER 


REINIT 


Clear the 4758 card (reset to manufactured state). 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these programs. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: 
char * new time 16 characters 


Example: 
CALL PGM(REINIT) 


Use these commands to compile this program on iSeries: 

CRTRPGMOD MODULE(REINIT) SRCFILE(SAMPLE) 

CRTPGM PGM(REINIT) MODULE(REINIT) 
BNDSRVPGM(QCCA/CSUACFC) 


Note: Authority to the CSUACFC service program in the 
QCCA library is assumed. 


The Common Cryptographic Architecture (CCA) verbs used are 
Cryptographic_Facilty Control (CSUACFC) 


KKKKKKKKK KKK KKK KKK KEKE KK KKK KKK KKK KKK KK KKK KKK KKK KEKKKKKEKREKERE 


Declare variables for CCA SAPI calls 
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Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

D* «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Verb data length 
DVERBDATALEN S 9B 0 

D* ** Verb data 

DVERBDATA S 8 

Dx« 
P¥eSeeSecssossesocsossessecscesesessessseseeossoss 
D* Declares for calculating one's complement 

PeeseSe cesses ese sess sees ce eee Slee ee eee see 
DBUFFER DS 

DA1 1 2 

DA2 3 4 

DA3 5 6 

DA4 7 8 

Dx« 

DWORKBUFF DS 

DINT4 1 4B 0 

DINT2 3 4 

Dx« 

Dx« 

DARK R KKK KKK KK ER KKK KKK KK KKK KKK KEK K KEKE KEK KERR KEK KR ERR KR RKR KK REE 
D* Prototype for Cryptographic_Facilty_Control (CSUACFC) 


DA RRA KKKK KKK KER KKK KEK KKK ERK KERR RRR KERR ERK RER KERR KER ERR ERK RERERER 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 8 

Dx« 

Peecetetese eee eee eee eee eee eee eet ese S ee ee See ee 
Dx **x Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Deeceeeeoseeee eee eee eee eee eee ee eee ee eee eee coe eee eee 
DMSG S 75 DIM(3) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(64) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

C* 

CR KKK KKK KEK KKK KKK KKK KEK KKK ERE KKK KERR K KKK KERR EKER KERR EKER ERK EKER E 
Cx START OF PROGRAM * 
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Cx* * 
CkeaeSSece sesso Se eeeese sees eee see tesae eee Se ese eee eee * 
Cx Set the keyword in the rule array * 
CeecceSleecesasseosocsceSeeossee sesso s ese sSacesia sss Soe eose * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "RQ-TOKEN' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

Cxkseesessa seas csacee sees ossesseseesocsesstcoscseScesssecceseee * 
Cx Set the verb data length to 8 * 
CxesebtecosstsseltectealesocesessseteseesssassseseossessesesScece * 
C Z-ADD 8 VERBDATALEN 

CR KKK KK KKK KKK KEKE KKK KE RK ER ERK KK RK EKER KEKE RR ERE RRR ER ERE RR ERR ERE 
Cx Call Cryptographic Facilty Control SAPI x*/ 
CR KKK KK KKK KKK KKK KEK RK KEK KEK ERK KK EKER KEK KEKE KR ERK RR EKER KER ERR ERE 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 
Cxsecsessescecessceesee se * 

Cx Check the return code * 

Cxseeeteeceeset sce Sees * 

C RETURNCODE IFGT 4 

Cx« tscacceesSesesscessesss * 

Cx * Send error message * 

Cx« {csececeace= saseeeseSse * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 

Cx« heseseneeaeeeesaaeeseses see eesesseeceess * 

Cx * Send success message for the Ist step * 

Cx* (oo sace keene ea Roe see cae eine ome ea ee ceae a * 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx« 
CxkSessescesesssssceeseeescssessccestecsest css eseSseess asf Ssase * 
Cx Set the keyword in the rule array for 2nd step * 
Ckteteeedeoeeeectees looses ese cse see esac see ete cee eel ot Sees * 
C MOVE "RQ-REINT' RULEARRAY 

Cx« 

(deseo eeeceecemce se nscee eee ease eee scene ase seeseoseeeseeeee * 
Cx Convert the token into the one's complement of it * 
(dase bese eeee acoso ete snes eee este eee sce ese eee eens eeee aeeesee * 
C MOVE VERBDATA BUFFER 

C Z-ADD 0 INT4 

C MOVE Al INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 Al 

C MOVE A2 INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 A2 

C MOVE A3 INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 A3 

C MOVE A4 INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 A4 

C MOVE BUFFER VERBDATA 

Cx« 
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CR KKK KKK KKK KK EKER KERR ERK KK ERE KK RK EK KEK KKK KERR ER ERK RR EK ERE RK EKERKEE 


Cx Call Cryptographic Facilty Control SAPI */ 
CR KKK KKK KEK KKK KK EK KKK ERK ER ERE RK RK EKER KEK ERR ER ERE RR EK ERE RR EKER 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C VERBDATALEN: 
C VERBDATA) 
CxXsetosceenesacsceseeeos= * 

Cx Check the return code * 

CX eevee ne eee essen seen ese * 

C RETURNCODE IFGT 4 

C* Ce eee ee * 

Cx * Send error message * 

Cx Pesseeesee ence see e ose * 

C MOVEL MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx* 

C ELSE 

C* Keseeeieesesesseceecoees * 

Cx * Send success message * 

Cx Kees cows ecaessossessess * 

C MOVE MSG (3) MSGTEXT 

C EXSR SNDMSG 

Cx* 

Cc ENDIF 

C SETON LR 
Cx* 


CR KKK KKK KKK KK KKK KR KEKE KKK KR ERE KKK EK KEK KKK KERR EK ERK RRR ERE RR EKER 


Cx Subroutine to send a message 
CR KKK KK KEKE KKK KKK KKK EKER KERR ER ERK EKER ERR EKER KER ERR RRR ERE RR EKER 


C SNDMSG BEGSR 

C CALL "QMHSNDPM ' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 


CSUACFC failed with return/reason codes 9999/9999. 
Random token was successfully returned. 
The Cryptographic Coprocessor successfully cleared/reset. 


Use the Hardware Service Manager 


Hardware service manager is a tool for displaying and working with system 
hardware from both a logical and a packaging viewpoint, an aid for debugging 
Input/Output (I/O) processors and devices, and is also used to reinitialize the 
4758 Coprocessor (set it back to an uninitialized state). 


When the 4758 Coprocessor is re-initialized, the 4758 Coprocessor Licensed Internal 
Code is reloaded into the Coprocessor. Some but not all program temporary fixes 
(PTFs) for the Coprocessor licensed internal code may require the use of hardware 
service manager to activate them. This extra step is included to allow you to 
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prepare for recovery because reloading certain segments of the licensed internal 
code will cause any configuration data including master keys, retained RSA private 
keys, roles, and profiles to be lost. 


There may be situations where the 4758 Coprocessor must be reset back to an 
unintialized state. For example, if the Coprocessor is not configured correctly, there 
could be a scenario where the Coprocessor can not perform any useful function 
and cannot be corrected using the 4758 Coprocessor configuration utility or a 
user-written application. Another example is if the passwords for the 
administrative profiles are forgotten and no other profile uses a role that is 
authorized to change passwords. 


Hardware service manager is found in System Service Tools. Use the Start System 
Service Tools (STRSST) CL command by typing STRSST at the CL command line 
and pressing enter. The System Service Tools Signon display should be shown. 


Start Service Tools (STRSST) Sign On 


SYSTEM: RCHSYSO1 
Type choice, press Enter. 


Service tools user. .... 
Service tools password... 


(aes F9=Change Password F12=Cancel 


Z 


Enter the service tools user profile name and password. The System Service Tools 
display should appear. 
e 


~_ 
System Service Tools (SST) 


Select one of the following: 


. Start a service tool 

. Work with active service tools 

. Work with disk units 

. Work with diskette data recovery 
. Work with system partitions 

. Work with system capacity 


DAorwNnr 


Selection 
1 


F3=Exit F10=Command entry F12=Cancel 
\ oy 


Select 1 to start a service tool and press Enter. The Start a Service Tool display will 
be shown. 
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Start a Service Tool 


Warning: Incorrect use of this service tool can cause damage 
to data in this system. Contact your service representative 
for assistance. 


Select one of the following: 


. Product activity log 

. Trace Licensed Internal Code 

. Work with communications trace 
. Display/Alter/Dump 

. Licensed Internal Code log 

. Main storage dump manager 

. Hardware service manager 


NOOR WN 


Selection 
7 


F3=Exit F12=Cancel F16=SST menu 


‘ 


4 


Select 7 to start Hardware Service Manager. The Hardware Service Manager screen 


will be displayed showing the menu of available options. 


Hardware Service Manager 
Attention: This utility is provided for service representative use only. 


System unit. ..... . : 9406-270 10-4314M 
Release ......... : V5RIMO (1) 


Select one of the following: 


1. Packaging hardware resources (systems, frames, cards,...) 
2. Logical hardware resources (buses, IOPs, controllers,...) 
3. Locate resource by resource name 
4. Failed and non-reporting hardware resources 
5. System power control network (SPCN) 
6. Work with service action log 
7. Display label location work sheet 
8. Device Concurrent Maintenance 
Selection 
2 
F3=Exit F6=Print configuration F9=Display card gap information 
F10=Display resources requiring attention F12=Cancel 


‘ 


Select 2 to work with logical hardware resources. 
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fa = 


Logical Hardware Resources 
Select one of the following: 


1. System bus resources 

2. Processor resources 

3. Main storage resources 

4. High-speed link resources 


Selection 
1 


F3=Exit F6=Print configuration F12=Cancel 
Se y 


From the Logical Hardware Resources screen, select 1 to show system bus 
resources. 


G » 


Logical Hardware Resources on System Bus 


System bus(es) to work with. ..... *ALL *ALL, *SPD, *PCI, 1-511 
SUDSCU: DY oe cater euct scree ane luen Osh eed cute se *CRP *ALL, *STG, *WS, *CMN, *CRP 


Type options, press Enter. 
2=Change detail 4=Remove 5=Display detail 6=1/0 Debug 


8=Associated packaging resource(s) 9=Resources associated with IOP 
Resource 
Opt Description Type-Model Status Name 
_ HSL 1/0 Bridge 2249- Operational BCO2 
Bus Expansion Adapter - Operational BCCO2 
System Bus 2249- Operational LBO1 
Multi-Adapter Bridge 2249- Operational PCIO1D 
a Combined Function IOP * < 284D-001 Operational CMBO1 
_ HSL 1/0 Bridge 283B- Operational BCO1 
Bus Expansion Adapter - Operational BCCO3 
More... 


F3=Exit F5=Refresh  F6=Print F8=Include non-reporting resources 
F9=Failed resources F10=Non-reporting resources 
Oia serial/part numbers F12=Cancel 


of 


If you know which IOP contains the 4758, type 9 next to the IOP. Otherwise, subset 
the list by typing *CRP for "Subset by” field and then type 9 next to the IOP 
containing the 4758. You should then see the Logical Hardware Resources 
Associated with IOP display. 
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a > 
Logical Hardware Resources Associated with IOP 
Type options, press enter. 
2=Change detail 4=Remove 5=Display detail 6=1/0 Debug 
7=Verify 8=Associated packaging resource(s) 
Resource 
Opt Description Type-Model Status Name 
Combined function IOP * < 284D-001 Operational CMBO1 
_ Cryptography Adapter 4758-023 Operational CRPCTLO1 
6 Cryptography Device 4758-023 Operational CRPO1 
Workstation IOA 2746-001 Operational CTLO1 
Display Station 3477-OFC Operational DSP001 
Display Station 3477-OFC Operational DSP002 
Communications I0A 2745-001 Operational LINO1 
£ Communications Port 2745-001 Operational CMNO1 
2 Communications Port 2745-001 Operational CMNO2 
Communications IOA 2744-001 Operational LINO3 
Communications Port 2744-001 Operational CMNQ3 
More... 
F3=Exit F5=Refresh Fo=Print F8=Include non-reporting resources 
F9=Failed resources F10=Non-reporting resources 
Fll=Display serial/part numbers F12=Cancel 
XX 4 
Type 6 next to the cryptography device that you want to reinitialize, and then 
press Enter. 
Select Cryptography Debug Function 
Select one of the following: 
1. Reinitialize Flash Memory 
2. Select IOP Debug Function 
Selection 
4 
F3=Exit F12=Cancel 
Ne S 


Select 1 to reinitialize flash memory (reload the 4758 Coprocessor Licensed Internal 


Code). A confirmation screen will be displayed. If you are applying a PTF ensure 


that you have taken the necessary precautions regarding your encrypted data and 


keys, and have a backup of the master key. Press Enter to continue. 
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Reinitialize Flash Memory Function 


DANGER: 
Performing this initialization of the flash memory on the cryptography 
device will cause ALL key information stored on the device to be 


DESTROYED. This will cause all data encrypted using this device to be 
rendered unusable. 


WARNING: 


Performing this initialization of the flash memory on the cryptography 
device will take an estimated 10 minutes. 


Press Enter to proceed. 


F3=Exit F12=Cancel 
Ne y 


The following screen showing status of the reinitialization will be displayed and 


updated until reinitialization is complete. 
a \ 


Reinitialize Flash Memory Status 


Flash memory reinitialization in progress... 


Estimated time: 10.0 minutes 


Elapsed time: 2.5 minutes 


a ae 


When reinitialization is complete, a message will be displayed. 
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Select Cryptography Debug Function 
Select one of the following: 


1. Reinitialize Flash Memory 
2. Select IOP Debug Function 


Selection 


F3=Exit F12=Cancel 
Reinitialization of cryptography device was successful. 


After reinitialization is complete, exit all the way out of system service tools by 
pressing function key F3 on each screen as necessary. 
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Chapter 5. Related information for cryptographic hardware 


a 


The following resources provide additional information relating to cryptographic 
concepts or hardware: 


IBM Redbooks” 


IBM @server iSeries Wired Network Security: OS/400 V5R1 DCM and 
Cryptographic Enhancements 


& 


IBM Sources 


* The|IBM Cryptographic hardware site contains information on the 4758 


Cryptographic Coprocessor hardware solution for iSeries servers. 


- The|CCA Basic Services Manuall™ is intended for systems and applications 


analysts and application programmers who will evaluate or create programs for 
the IBM 4758 Common Cryptographic Architecture (CCA) support. 


* The|IBM PCI Cryptographic Coprocessor documentation librar ad contains 


downloadable PDF documents that include general, support, and programming 
information for the 4758 Cryptographic Coprocessor. 


* The IBM |developerWorks|“ site includes tutorials for cryptographic concepts, 
cryptography, and encryption. 


% 
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Chapter 6. Code disclaimer information 


This document contains programming examples. 


IBM grants you a nonexclusive copyright license to use all programming code 
examples from which you can generate similar function tailored to your own 
specific needs. 


All sample code is provided by IBM for illustrative purposes only. These examples 
have not been thoroughly tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function of these programs. 


All programs contained herein are provided to you "AS IS” without any warranties 


of any kind. The implied warranties of non-infringement, merchantability and 
fitness for a particular purpose are expressly disclaimed. 
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